devcontainer.json
Devsy uses the open devcontainer.json standard to define a project's development container. VS Code and GitHub Codespaces use the same format, so existing configurations work in Devsy.
If a project has no configuration, Devsy detects the language and uses a default.
For the full format, see the reference, the VS Code documentation, and the Codespaces documentation.
Where the file lives
Devsy looks for one of:
.devcontainer/devcontainer.json.devcontainer.json.devcontainer/<folder>/devcontainer.json
To use a specific file, pass its path:
devsy workspace up github.com/my-org/my-repo --devcontainer ./path/to/devcontainer.jsonUse extends to inherit from other files. It takes a path or a list of paths. Keep the files a configuration depends on inside its folder.
Existing workspaces
Devsy remembers which configuration each workspace uses. If a later search finds a different file, Devsy warns and keeps the saved one. To switch files, recreate the workspace:
devsy workspace up <workspace> --recreate --devcontainer "<relative-path>"
devsy workspace up <workspace> --recreate --devcontainer "id:<name>"Devsy saves the choice for later runs.
Dockerfile
{
"build": {
"dockerfile": "Dockerfile"
}
}Docker Compose
Set dockerComposeFile to one or more Compose files. Set service to the service that runs as the dev container:
{
"dockerComposeFile": ["docker-compose.yml", "docker-compose.dev.yml"],
"service": "backend"
}Devsy names the Compose project the same way Docker Compose does, so it reuses a project that is already running. It checks these sources in order:
COMPOSE_PROJECT_NAMEin your shell.COMPOSE_PROJECT_NAMEin an.envfile, in the devcontainer folder, the workspace root, or a compose file's folder.- The top-level
name:in the compose files. The last file that sets it wins. - A name derived from the workspace.
The name field in devcontainer.json is only a display name and never names the compose project.
A custom DOCKER_HOST set for the Docker provider is passed to the docker compose commands Devsy runs.
Features
Features are reusable pieces that Devsy merges into your Dockerfile, such as docker-in-docker or kubectl.
To send HTTP headers when Devsy downloads a feature archive, set them under customizations:
{
"features": {
"https://example.com/foo_feature.tar.gz": {}
},
"customizations": {
"devsy": {
"featureDownloadHTTPHeaders": {
"FOO_HEADER": "${localEnv:FOO_ENV_VAR}",
"BAR_HEADER": "bar"
}
}
}
}Applying changes
After you edit the configuration, apply it without deleting the workspace:
Recreating
Anything outside volumes is lost. The project folder and other mounted paths stay.
devsy workspace up my-workspace --recreateDevsy builds and validates the new image before stopping or replacing the existing container. If the build fails, the existing workspace stays in its previous state, whether running or stopped. A later failure can leave the old container stopped or removed, depending on the provider. Pass --recovery to start a recovery container with features and lifecycle commands disabled if the build fails.
postStartCommand and waitFor
waitFor names the lifecycle hook that devsy workspace up waits for before it returns. The default is updateContentCommand, so postStartCommand can finish after up returns.
A postStartCommand that asks for input needs an attached terminal. Add --interactive-post-start to that devsy workspace up run. The option does not change waitFor in this file. For the details and limits, see Answer prompts in postStartCommand.
Environment variables in devcontainer.json
With the SSH provider, the variable in ${localEnv:NAME} must reach the remote machine.
-
Reference the variable in
devcontainer.json:{ "name": "Node.js", "image": "mcr.microsoft.com/devcontainers/javascript-node:${localEnv:IMAGE_VERSION}" } -
Send it from your local
~/.ssh/config:Host <REMOTE-SSH-SERVER> SetEnv IMAGE_VERSION=0-18-bullseye -
On the remote machine, add
AcceptEnv IMAGE_VERSIONto/etc/ssh/sshd_configand restart the SSH service. -
Start the workspace:
devsy workspace up <GITHUB-REPOSITORY-URL> --provider ssh --ide=none
Reserved labels
Devsy owns the following labels in the explicit label maps it sends to drivers and external providers:
devsy.usersh.devsy.recoverydevsy.overlay.structuredevsy.sh/metadata-creation-configdevsy.compose.contractdevsy.compose.invocationdevsy.wslg.snapshotdevsy.sh/userdevsy.sh/microsandbox-workspace-mountdevsy.sh/microsandbox-workspace-usersh.devsy.managedsh.devsy.workspace-idsh.devsy.resourcesh.devsy.volume-rolesh.devsy.seededdevsy.sh/createddevsy.sh/workspace-uiddevsy.sh/manageddevsy.sh/resourcedevsy.sh/volume-role
Do not supply these keys through --id-label, Kubernetes provider labels, or Kubernetes pod template labels. Devsy rejects them with an error naming the key. This also applies to saved workspace options. Remove the assignment before starting an older workspace again. Devsy still writes its own values for these keys.
Custom identification labels, including dev.containers.id, remain configurable. The devcontainer.metadata image label remains a supported configuration source and can contain private values. Reserving a label does not make every value stored under it public.
The top-level containerLabels and labels fields in devcontainer.json are ignored. External providers reject runArgs rather than translate them into request labels. Native Docker, Podman, nerdctl, Apple and Compose arguments and inherited image labels are outside this explicit map reservation. Avoid using reserved keys there. Native argument validation is a separate follow-up.