Skip to main content

Working with Sandbox

OneDev can run CI/CD jobs and development workspaces in Docker Sandboxes, which isolate project commands and tools in virtual machines on the OneDev server or an agent host. Sandbox executors provide isolated environments for running jobs, while sandbox provisioners provide isolated environments for development workspaces.

Before following this tutorial, install Docker Sandboxes on every host that will run sandboxes. The host must be a physical machine with hardware virtualization enabled, or a virtual machine with nested virtualization supported and enabled.

This guide covers host setup, unattended login, template registry access, and security settings for local sandboxes.

How Sandboxes Work​

The host runs the Docker Sandboxes daemon; the guest is the sandbox VM. A template provides the VM image and installed tools. A kit adds runtime settings, such as credential requests.

OneDev's custom kit disables the built-in shell kit's service credential forwarding and shared host skills. SSH-agent forwarding and the MCP gateway remain available. Review the security practices before running untrusted code.

Set Up Docker Sandbox Login​

Use a Docker personal access token (PAT) for unattended login. This requires no browser on the sandbox host.

Choose the Host and Service Account​

Use a dedicated service account with a persistent, writable home directory. On Linux, this account must have KVM access. Keep personal sandboxes, SSH identities, API credentials, and MCP registrations in a separate account.

Run login and all host commands below as the account that launches sbx, using the same home directory and any custom XDG_CONFIG_HOME or XDG_STATE_HOME settings. Preserve its configuration and credential storage across restarts and reboots.

Create a Non-Expiring PAT​

Sign in to Docker Home and open Account settings:

  1. Open Personal access tokens and select Generate new token.
  2. Give it a recognizable description, such as OneDev sandbox host.
  3. Set Expiration date to None.
  4. Grant read access to the template images you need. For Docker's public templates, public repository read access is sufficient.
  5. Generate the token and save it in your credential manager.

Keep this token on the host. It authenticates sbx and should not be passed into sandboxes. See Docker's personal access token guide for details.

Sign In as the Service Account​

On each sandbox host, open a terminal as the OS user that runs the service. Set DOCKER_PAT to the access token created above, then run:

echo "$DOCKER_PAT" | sbx login --username YOUR_DOCKER_ID --password-stdin

Replace YOUR_DOCKER_ID with your Docker username. The two flags explicitly select token-based login. Logging in as a different OS user does not configure the service account.

Keep the Login Available​

Sandbox creation and service restarts reuse the stored login. If the PAT is revoked or deactivated, sign in with a new token. Repeat login if stored credentials are removed or become inaccessible. A non-expiring PAT still depends on Docker's authentication service.

Pull Private Template Images​

Configure registry access on each sandbox host under the service account. For Docker Hub, use sbx login with a PAT that can read the template repository. For other registries, run:

sbx secret set --registry registry.example.com

Replace registry.example.com with your registry hostname. Keep the default host-only scope; do not add --all-sandboxes. See Docker's registry credentials guide.

Security Practices​

Run host commands as the service account configured above. Review these controls after configuration changes or sbx upgrades. See Docker's security model for details.

Disable Host SSH Agent Forwarding​

SSH-agent forwarding is enabled by default. Sandbox processes can use host keys to authenticate without reading the private keys. Disable forwarding before running untrusted code, restarting the daemon when no sandboxes are in use:

sbx settings set ssh.agentForwardingEnabled false
sbx daemon restart
sbx settings get ssh.agentForwardingEnabled

The last command should report false. Clearing SSH_AUTH_SOCK inside the guest does not disable forwarding. See Docker's SSH settings.

Restrict Host Credentials​

Custom secrets (sbx secret set-custom) and registry credentials shared with sandboxes have separate controls from kit service credentials. Inspect stored entries:

sbx secret ls

Keep unrelated credentials out of the service account, avoid sbx secret import --all, and keep template registry credentials host-only. Proxy authentication can grant access even when sandbox code cannot read the secret. See Docker's credential handling.

Restrict MCP Tools​

Docker's MCP gateway remains active without agent MCP configuration. Its default dynamic mode lets sandbox code discover and attach registered servers. Command-based MCP servers run on the host and may expose host files or remote services. Inspect registrations:

sbx mcp ls

Keep unrelated MCP registrations and authorizations out of the service account. The current CLI and v2 kit format provide no supported MCP off switch; an empty catalog limits tools but does not disable the gateway. Apply organization MCP access policies where available.

Restrict Other Host Integrations​

Disable host browser opening and clipboard image access when unnecessary:

sbx settings set browser.enabled false
sbx settings set clipboard.imagePaste false

See Docker's host access settings.

Further Reading​

With your sandbox hosts configured, follow these guides to build templates with or without Docker support, publish them to Docker Hub, and use them in OneDev: