Skip to content

Add the docker-sbx provider - #11

Merged
czpython merged 1 commit into
mainfrom
docker-sandbox-provider
Aug 18, 2026
Merged

Add the docker-sbx provider#11
czpython merged 1 commit into
mainfrom
docker-sandbox-provider

Conversation

@czpython

@czpython czpython commented Aug 18, 2026

Copy link
Copy Markdown
Owner

Closes #8.

Summary

This change adds the docker-sbx VM provider. The provider runs each host as a Docker Sandboxes microVM. Each microVM has its own kernel, its own filesystem, and its own Docker daemon. This gives more isolation than the local docker provider.

Changes

  • src/providers/docker_sbx/ contains the provider. The SbxCLI class starts the sbx command as an async subprocess. The settings use the DOCKER_SBX_ prefix.
  • images/sbx/ contains the sandbox template. The template starts sshd and does not need environment variables. The sbx create command cannot send environment variables.
  • The provider injects the SSH key and the caller environment with sbx exec. The script goes through stdin. Secrets do not go on the command line.
  • The provider publishes port 22 on the DOCKER_SBX_ADVERTISE_HOST address. The daemon selects a free host port.
  • The provider always sets --cpus and --memory. Without these flags, the daemon gives one sandbox all host CPUs and half of the host memory.
  • The provider sets supports_tailnet to False. The service does not send a Tailscale setup script to this provider.
  • docs/deploy.md shows the host prerequisites and the container configuration. The host owns the sbx installation, the login, and the daemon. A drukbox container connects through a socket mount and the DOCKER_SANDBOXES_API variable.

Review

An adversarial review found 10 problems. This PR fixes all of them:

  • The provider did not set supports_tailnet to False. A tailnet-mode service made a Tailscale key for each host and then lost it.
  • The template entrypoint made the authorized_keys file empty at each start. A restart of a sandbox removed the SSH key.
  • The error check matched all messages that contain "not found". A login error could delete the record and the workspace of a live sandbox.
  • A workspace mkdir error went around the provider error boundary. The host record stopped in a state that blocks deletion.
  • A failed create did not remove a partially created sandbox.
  • An IPv6 address made an incorrect port specification. Brackets are necessary for IPv6.
  • The bootstrap script wrote the key only for the root user. The ssh_username setting had no effect.
  • The sbx calls had no time limit. A blocked daemon stopped requests permanently. The limit is now 600 seconds.
  • The workspace removal blocked the event loop. The removal now runs in a thread.
  • docs/networking.md did not show the new provider.

Verification

  • uv run ruff check: pass
  • uv run ruff format --check: pass
  • uv run pyright: 0 errors
  • uv run pytest: 377 tests pass

Known limits

  • The conformance suite (api-tests) did not run against a live deployment.
  • The image ghcr.io/czpython/drukbox/sbx-sandbox:latest does not exist yet. Build and push the image before deployment.
  • Sandboxes have no SERVICE_LABEL tag. The sbx CLI has no label option. Give each deployment its own daemon.

@czpython czpython changed the title Add docker-sandbox provider backed by Docker Sandboxes microVMs Add the docker-sandbox provider Aug 18, 2026
@czpython
czpython force-pushed the docker-sandbox-provider branch 6 times, most recently from 5c7c1d0 to 219048c Compare August 18, 2026 14:46
The provider runs each host as a Docker Sandboxes microVM. The template
image starts sshd and does not need environment variables. The provider
injects the SSH key and the caller environment with sbx exec. Then it
publishes port 22 on a host port that the daemon selects.

The provider sets supports_tailnet to False. The host machine owns the
sbx installation, the login, and the daemon. A drukbox container
connects through a socket mount and the DOCKER_SANDBOXES_API variable.
The images/sbx/ directory contains the template.
@czpython
czpython force-pushed the docker-sandbox-provider branch from 219048c to 33c0290 Compare August 18, 2026 14:49
@czpython czpython changed the title Add the docker-sandbox provider Add the docker-sbx provider Aug 18, 2026
@czpython
czpython merged commit b7ccdec into main Aug 18, 2026
6 checks passed
@czpython
czpython deleted the docker-sandbox-provider branch August 18, 2026 14:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add a Docker Sandboxes (sbx) microVM provider

1 participant