Workspace Planning

Workspace planning turns repository files into a deterministic WorkspacePlan. The plan is the bridge between source checkout, the current container runtime, CellOS workspace initialization, and Firecracker machine configuration.

Inputs

The local planner discovers:

• .devcontainer/devcontainer.json;
• root .devcontainer.json;
• Dockerfile builds referenced by devcontainer config;
• Compose files referenced by dockerComposeFile;
• features, mounts, environment, forwarded ports, and workspace folder.
• devcontainer secrets and post-create/start/attach commands for execution planning.

JSONC comments are accepted in devcontainer files. Compose YAML and Dockerfiles are parsed into a smaller normalized shape rather than treated as raw strings.

Output

The normalized plan records:

• image or build metadata;
• Dockerfile base images and instruction names;
• Compose service names, images/build contexts, ports, and env;
• devcontainer features and options;
• mounts and environment;
• ports and workspace path.

For the guest handoff, devcell can derive a CellOS execution plan:

devcell workspace plan examples/workspaces/devcontainer-execution --execution --json

That plan carries the runtime, workspace folder, selected service, build inputs, Compose services, features, mounts, environment, ports, secrets, devcontainer commands, and target GuestService.InitializeWorkspace contract.

The planner is intentionally pragmatic. It does not replace the upstream Dev Container CLI. It decides what the cell should run, while build and lifecycle commands execute on the workload side of the boundary rather than in celld.

projectdevcontainer.json

servicesCompose files

imageDockerfile

normalizeWorkspacePlandeterministic contract

→

guestCellOS planworkspace init

+

machineFirecracker modelruntime config