`docker ps` fails inside sandbox when using a custom template

[kkyr]

Summary

Running sbx run with the default template gives a working Docker daemon inside the sandbox — docker ps succeeds and /var/run/docker.sock is present. But building any custom template that merely FROMs a stock template (including the non-minimal docker/sandbox-templates:claude-code) produces a sandbox where dockerd is not running and the socket is missing.

This looks like the sandbox runtime treats the built-in default templates specially (starting dockerd as part of sandbox boot), and that special treatment does not carry over to user-built templates derived from them.

Reproduction

Minimal Dockerfile:

FROM docker/sandbox-templates:claude-code
USER agent

Build and run:

docker build -t custom-repro .
sbx create --name repro --template custom-repro:latest claude "$PWD"
sbx exec -i repro bash

Inside the sandbox:

agent@repro:~$ docker --version
Docker version 29.4.0, build 9d7ad9f

agent@repro:~$ docker ps
failed to connect to the docker API at unix:///var/run/docker.sock;
check if the path is correct and if the daemon is running:
dial unix /var/run/docker.sock: connect: no such file or directory

agent@repro:~$ pgrep dockerd || echo "dockerd not running"
dockerd not running

For comparison, inside a sandbox created with the default template (sbx run, no custom Dockerfile):

agent@default:~$ pgrep dockerd
42
agent@default:~$ docker ps
CONTAINER ID IMAGE COMMAND ...

Same behaviour observed with FROM docker/sandbox-templates:claude-code-minimal.

Expected behaviour

A sandbox built from FROM docker/sandbox-templates:claude-code should behave like the default sbx run sandbox — dockerd running, socket present, docker ps working — without any extra configuration in the user's Dockerfile.

If starting dockerd is the user's responsibility when customising a template, please document:

- The exact init command (service docker start? dockerd &? something else?)
- Where it should be wired in (/etc/sandbox-persistent.sh? an entrypoint? a build-time flag?)
- Any sandbox-runtime flags needed to allow dockerd to run (cgroups, iptables, storage driver).

Environment

• sbx CLI: 0.26.1
• Host OS: macOS
• Templates tested: docker/sandbox-templates:claude-code, docker/sandbox-templates:claude-code-minimal

[mooseracerPT]

Those templates you tried don't include the docker engine, your base image needs a -docker on the end of the name. https://docs.docker.com/ai/sandboxes/agents/custom-environments/#base-images

FROM docker/sandbox-templates:claude-code-docker
...