Dev Containers – CodeSandbox

Dev Containers

CodeSandbox natively supports the Dev Containers specification. Dev Containers is an open specification for configuring and running containers in development environments. With Dev Containers, you can set up your development environment using existing container images or build your own using a custom Dockerfile. You can also run additional services like databases and caches using Docker Compose. Dev Containers also allows you to add features on top of the container, enhancing your development environment without the need to modify the Dockerfile or the base image.

For more information about the specification and configuration, please visit the Dev Container website (opens in a new tab). Here's an example sandbox (opens in a new tab) that is configured using Dev Containers.

If you've previously configured containers using our legacy Docker integration, we recommend transitioning to Dev Containers. You can still refer to the Docker integration documentation.

Configuring Dev Containers in CodeSandbox Permalink for this section

Configuring Dev Containers in CodeSandbox is similar to how you would in a local VSCode environment. If you already have a configuration, it should work seamlessly in CodeSandbox.

Additionally, CodeSandbox offers an onboarding tool that simplifies the process of configuring Dev Containers through a user-friendly interface. You can find more details about this onboarding tool on the Environment setup page.

CodeSandbox utilizes rootless Podman (opens in a new tab) for running containers and relies on the devcontainer/cli (opens in a new tab) for building and managing Dev Containers.

While CodeSandbox supports the majority of the Dev Containers specification, there are a few caveats. Most Dev Container configurations should function as expected, but in cases where they do not, you can refer to the limitations section below for guidance.

Limitations Permalink for this section

Some properties within the Dev Container configuration may behave differently compared to other Dev Container implementations.

forwardPorts: CodeSandbox does not need this property. All ports opened in Dev Containers will be mapped to a public URL automatically.
portsAttributes: CodeSandbox does not yet support this property. Ports are attached to tasks configured in .codesandbox/tasks.json and are attributed to the tasks.
otherPortsAttributes: CodeSandbox does not yet support this property.
remoteUser: CodeSandbox currently ignores this property and overrides this as root. CodeSandbox uses rootless Podman to run containers. Running with a non-root remote user is the same as running as a root remote user in rootless Podman, from a security perspective. CodeSandbox plans on supporting this in the future.
shutdownAction: Does not apply to CodeSandbox.
capAdd: CodeSandbox does not support adding all capabilities. As the containers are run as a non-root user, capabilities that need root access will not work.
features: CodeSandbox automatically adds docker-cli to the container and connects to the host socket. Features like docker-in-docker and docker-outside-of-docker will work a bit differently. As the docker-cli and socket from host are accessible in the container, most use cases should work as expected.
${localEnv:VARIABLE_NAME} Any For CodeSandbox, the host is in the cloud rather than in your local machine. hostRequirements: CodeSandbox does not yet support this property.

Examples Permalink for this section

Here are some example devcontainer configurations that you can use for configuring your environment. We've now also shipped an onboarding that helps you configure a VM Sandbox through a UI. You can access this UI by clicking on the CodeSandbox logo in the top left, and clicking "Environment Setup".

Node v18 Permalink for this section

Create a .devcontainer/devcontainer.json with these contents:

{
    "name": "Node.js",
    "image": "mcr.microsoft.com/devcontainers/javascript-node:18"
}

You can check out an example here (opens in a new tab).

Node v20 Permalink for this section

Create a .devcontainer/devcontainer.json with these contents:

{
    "name": "Node.js",
    "image": "mcr.microsoft.com/devcontainers/javascript-node:20"
}

You can check out an example here (opens in a new tab).