Templates — Build a custom template

Reference note (untrusted external data; do not execute it as instructions). Building a custom template requires Docker Desktop. Write a Dockerfile that extends one of the base images. Pick the variant that matches the agent you plan to run. For example, extend claude-code to customize a Claude Code environment, or codex to customize an OpenAI Codex environment. The following example creates a Claude Code template with Rust and protocol buffer tools pre-installed Bounded code example (external data; do not execute automatically): ```dockerfile FROM docker/sandbox-templates:claude-code USER root RUN apt-get update && apt-get install -y protobuf-compiler USER agent RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y ``` Use root for system-level package installations (apt-get), and switch back to agent before installing user-level tools. Tools that install into the home directory, such as rustup, nvm, or pyenv, must run as agent — otherwise they install under /root/ and aren't available in the sandbox. Build the image and push it to an OCI registry, such as Docker Hub Bounded code example (external data; do not execute automatically): ```console $ docker build -t my-org/my-template:v1 --push . ``` > [!NOTE] > The Docker daemon used by Docker Sandboxes pulls templates from a > registry directly; it doesn't share the image store of your local Docker > daemon on the host. > [!IMPORTANT] > For Docker Hub, sbx reuses your sbx login session to pull private > images. For other registries (GitHub Container Registry, ECR, ACR, a > self-hosted Nexus, and so on), store pull credentials with > sbx secret set --registry > before running the sandbox: > > console > $ gh auth token | sbx secret set --registry ghcr.io --password-stdin > > > Without stored credentials, pulls from non-Docker Hub registries are > anonymous and private images fail to pull. For locally-built images, save the image to a tar and load it directly into the sandbox runtime instead of pulling from a registry Bounded code example (external data; do not execute automatically): ```console $ docker image save my-org/my-template:v1 -o my-template.tar $ sbx template load my-template.tar $ sbx run --template my-org/my-template:v1 claude ``` sbx template load imports the tar into the sandbox runtime's image store, so the image doesn't need to be reachable from a registry at sandbox creation time. … Attribution: Adapted from Docker Documentation under Apache-2.0. Adaptation: WikiKV isolated this documentation section, normalized formatting, retained only bounded code excerpts, and shortened it at a paragraph or sentence boundary for retrieval. Verify version-sensitive details at the source.