Devsy
Developing in a Workspace

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.json

Use 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:

  1. COMPOSE_PROJECT_NAME in your shell.
  2. COMPOSE_PROJECT_NAME in an .env file, in the devcontainer folder, the workspace root, or a compose file's folder.
  3. The top-level name: in the compose files. The last file that sets it wins.
  4. 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 --recreate

Devsy 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.

  1. Reference the variable in devcontainer.json:

    {
      "name": "Node.js",
      "image": "mcr.microsoft.com/devcontainers/javascript-node:${localEnv:IMAGE_VERSION}"
    }
  2. Send it from your local ~/.ssh/config:

    Host <REMOTE-SSH-SERVER>
       SetEnv IMAGE_VERSION=0-18-bullseye
  3. On the remote machine, add AcceptEnv IMAGE_VERSION to /etc/ssh/sshd_config and restart the SSH service.

  4. 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.user
  • sh.devsy.recovery
  • devsy.overlay.structure
  • devsy.sh/metadata-creation-config
  • devsy.compose.contract
  • devsy.compose.invocation
  • devsy.wslg.snapshot
  • devsy.sh/user
  • devsy.sh/microsandbox-workspace-mount
  • devsy.sh/microsandbox-workspace-user
  • sh.devsy.managed
  • sh.devsy.workspace-id
  • sh.devsy.resource
  • sh.devsy.volume-role
  • sh.devsy.seeded
  • devsy.sh/created
  • devsy.sh/workspace-uid
  • devsy.sh/managed
  • devsy.sh/resource
  • devsy.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.

On this page