We are in the process of deprecating this integration and shifting towards the Dev Containers specification. For more information about Dev Containers, please click here.
CodeSandbox has a native integration with Docker. This means that you can use Docker to install any package you want, including databases and new languages. Additionally, with the Docker integration you have root access within your terminals, so you can install packages from the terminal as well.
While we call this a Docker integration, we use rootless Podman (opens in a new tab) to run the containers.
You can find an example of a sandbox that uses Docker here (opens in a new tab).
To enable the Docker integration, you need to create a new file in
.codesandbox/Dockerfile, this is the Dockerfile that will be used to build the container for the environment. Whenever you open a new terminal, you will be inside this container.
When this file exists, we will also make sure to automatically rebuild the container when the VM boots.
For a step-by-step guide, check out our tutorial Getting started with Docker
With CodeSandbox, we allow you to share your sandbox with others easily by sharing a link. Because of this, we make sure to create a new Linux user for every user that opens the sandbox.
This means that we also have to run containers on a per-user basis. For every user, we create a rootless container using Podman based on the
Dockerfile configuration in the sandbox/repo. While the user outside of the container does not have root, inside the container they do have root access.
Whenever you open a terminal, we check if there is a container running for your user. If it's not running, we start it, and we then start an
exec session inside the container.
Every container does share the network, files and processes between each-other. This allows you to run an HTTP server in one container, and connect to it from another container.
To run additional services using the Docker Compose integration, you can create a file
.codesandbox/docker-compose.yml. This file will be used to run
docker compose up at a branch/sandbox startup. This feature can be used to run other services needed in the development environment like databases, proxies, etc.
For the Docker Compose integration to automatically start the
composecommand, the environment should be configured with
.codesandbox/Dockerfileas explained above.
To access these services, you have to expose the ports in the
docker-compose.yml file using the
ports attribute of the service.
services: nginx: image: nginx ports: - 8080:80
You can use Docker commands in the terminal to exec into the containers started with this method. To manage the running containers with the
docker compose command, either
cd into the
.codesandbox directory or specify the location of the
docker-compose.yml file using
docker compose -f .codesandbox/docker-compose.yml.
You do not have to run or configure a task to run
docker compose. The
.codesandbox/docker-compose.ymlfile will be automatically detected and
docker-compose upwill be run at branch/sandbox startup.
Normally, you would define in your
Dockerfile what the container should run when it boots. Since CodeSandbox has its own task management system (opens in a new tab), we don't run commands defined in
Dockerfile defined as
Instead, we recommend to create a
.codesandbox/tasks.json, and define your starting process from there. You can automatically do this by opening the command palette (CMD/Ctrl + Shift + P) and selecting "Generate task configuration". You can learn more about task configuration here (opens in a new tab).