Docker in sandboxes

Docker is preinstalled in most sandbox templates. There is nothing to enable.

docker run --rm alpine echo hello
docker compose up -d
docker buildx build --load -t myapp .

What each template ships today:

Template	Docker Engine	Compose and Buildx	Runs as `sandbox` user
`instant-code`	29.9	Yes	Yes, `sandbox` is in the `docker` group
SOMA runtime (`runtime_profile: "soma"`)	29.9	Yes	As `root`
`miosa-sandbox` and the templates built on it (`agent-browser`, `nextjs`, `nextjs-postgres`, `static-html`)	20.10	Not yet, they arrive with the next image release	As `root`
`fastapi-auth`	Not included	No	No

Commands run through exec run as root, so docker works there on every template above that includes it. Check what a sandbox has with docker version, docker compose version, and docker buildx version.

What works

Task	Works
`docker run`, `docker exec`, `docker logs`, volumes, bind mounts	Yes
`docker compose up` with several services and service-name DNS between them	Yes, on templates with Compose
`docker buildx build`	Yes, on templates with Buildx
`docker build`	Yes
Pulling from Docker Hub and other public registries	Yes
Publishing a port with `-p 8080:80` and opening it through a preview URL	Yes
Running as `root`	Yes
Running as the `sandbox` user	On `instant-code`
Pausing and resuming a sandbox with containers running	Yes, containers keep running

Startup behavior

On instant-code the Docker engine starts the first time you use it, not when the sandbox boots, so sandbox creation stays fast. The first docker command in a fresh sandbox takes about 0.6 seconds longer while the engine starts; after that, running an image that is already pulled takes about 0.15 seconds.

If you start containers with --restart always, they come back when the engine next starts, which happens on your next docker command.

Open a container port in your browser

Publish the port on the sandbox, then expose it as a preview.

docker run -d --name web -p 8080:80 nginx:alpine

The preview URL forwards to the published port. Bind to 0.0.0.0 inside the container, which -p does for you.

Disk and memory

Images, layers, and volumes live on the sandbox disk, so they count against its size. The default small sandbox has 10 GiB of disk. When the disk is full, a pull or build fails with no space left on device and the sandbox keeps running. Free space with docker system prune -af and retry.

The engine uses about 40 MiB of memory when idle. Containers share the sandbox’s CPU and memory.

Docker in a sandbox vs App Engine

You want	Use
Run, build, or test containers while you develop, or let an agent do it	Docker in a sandbox
A durable 24/7 deployment URL, custom domains, and rollback for a containerized app	App Engine
A sandbox whose only job is to be a Docker host with a long-lived disk	The `miosa-sandbox-docker` template

Docker in a sandbox is for development and automation. It is not a production runtime.

Templates

instant-code and SOMA-runtime sandboxes include Docker Engine 29.9 with Compose and Buildx.
miosa-sandbox, agent-browser, nextjs, nextjs-postgres, and static-html include Docker Engine 20.10. Compose and Buildx arrive with the next image release.
fastapi-auth does not include Docker.
miosa-sandbox-docker is a dedicated Docker host image. It starts the engine at boot and uses host networking for containers, so docker build there needs --network host.

Limits

No nested virtualization. KVM and QEMU do not run inside a sandbox.
Image builds for other CPU architectures need emulation that is not included.
Docker Swarm ingress is not supported.