Build a Sandbox Template

A sandbox template is a Docker image that provides the tools inside a OneDev workspace's sandbox VM. Preinstalling development tools in the template makes them available whenever you create a workspace.

This tutorial shows how to build templates with or without Docker support, publish them to Docker Hub, and use them in workspace specs:

Template	Use it for
Basic	Editing code and running development tools directly in the sandbox VM
With Docker	The same workflow, plus building images, running containers, and using Docker Compose

Prerequisites

First complete Working with Sandbox on every host that will run sandbox workspaces. It covers Docker Sandboxes installation, virtualization requirements, service account login, registry access, and security settings.

You also need:

• Docker on the machine used to build images, and a Docker Hub account.
• A sandbox provisioner configured under Administration → Workspace Provisioners: use Server Sandbox Provisioner to run workspaces on the OneDev server, or Remote Sandbox Provisioner to run them on agents. Remote provisioning requires Enterprise Edition.
• Permission to configure workspace specs and create workspaces in your project. See Working with Workspaces for the workspace workflow.

Define the Templates

Choose a Linux base image compatible with Docker Sandboxes that suits your project. The resulting template must include a shell, Git, Python 3, and tmux for workspace terminals. The examples below use Ubuntu; for another base image, adapt the package names and installation commands to provide the same required tools.

Without Docker

Create an empty directory and add a Dockerfile. For example:

FROM ubuntu:24.04
RUN apt-get update \
    && apt-get install -y git git-lfs python3 tmux \
    && rm -rf /var/lib/apt/lists/*

Ubuntu includes a shell; this example adds the remaining tools and Git LFS to support the workspace spec's default Retrieve LFS Files setting. Add your preferred editor, language runtimes, or coding agents as needed.

With Docker

For workspaces that need containers or Docker Compose, extend your template with Docker support. Save this example as Dockerfile.docker in the same directory:

FROM ubuntu:24.04
RUN apt-get update \
    && apt-get install -y curl git git-lfs python3 tmux \
        docker.io docker-buildx docker-compose-v2 \
    && rm -rf /var/lib/apt/lists/*
LABEL com.docker.sandboxes.start-docker="true"

This adds Docker Engine, Buildx, Compose v2 (docker compose), and curl for Docker Sandboxes' daemon readiness check. The image label enables Docker support and starts the daemon. Containers and Docker's image storage stay inside the sandbox VM.

Workspace terminals and setup commands run as the template image's default user. Both examples use root. If you choose a non-root user, ensure it can use the installed tools, including Docker when enabled.

Build and Publish to Docker Hub

Create a Docker Hub repository named onedev-workspace under your account. Replace YOUR_DOCKER_ID with your Docker Hub username and sign in:

docker login --username YOUR_DOCKER_ID

From the directory containing the Dockerfiles, build and push the variant you need using the corresponding commands below. These commands use the build machine's architecture. If the sandbox host uses a different architecture, add the appropriate --platform, such as --platform linux/amd64, to each build command. For mixed architectures, publish a multi-architecture image.

docker build -t docker.io/YOUR_DOCKER_ID/onedev-workspace:basic-v1 .
docker push docker.io/YOUR_DOCKER_ID/onedev-workspace:basic-v1

docker build -f Dockerfile.docker -t docker.io/YOUR_DOCKER_ID/onedev-workspace:docker-v1 .
docker push docker.io/YOUR_DOCKER_ID/onedev-workspace:docker-v1

Docker Sandboxes has a separate image store from the host's Docker Engine. Publish the images before using them in OneDev, and include docker.io/ in template references as shown above. See Docker's template loading guide.

For a private repository, configure the sandbox host's registry credentials with read access. A docker login on the image-building machine does not configure the sandbox host's sbx login account.

Use the Template in a Workspace

Open Settings → Workspace Specs in your project and select Create New:

1. Give the spec a name, such as Development Sandbox.
2. Set Provision Mode to Sandbox for either template variant.
3. Set Template to docker.io/YOUR_DOCKER_ID/onedev-workspace:basic-v1, or use the docker-v1 tag for Docker support.
4. Select the sandbox provisioner configured earlier under Provisioner, or leave it empty to use the first applicable sandbox provisioner.
5. Under Shell, choose POSIX Compatible Shell and set Shell Executable to bash, which is available in these examples. For another base image, choose a shell it provides.
6. Leave Shortcuts empty to open a regular terminal, then save the spec.

Create a workspace from a branch, tag, or commit using this spec. After provisioning finishes, run these commands in the workspace terminal:

git --version
git lfs version
python3 --version
tmux -V
git status --short

The version checks should succeed, and the terminal should open in your checked-out repository. You can now edit code and run your project's development commands. Add shortcuts for frequently used commands once the corresponding tools are installed in your template.

Use Docker in the Workspace

In a workspace created with the docker-v1 template, verify Docker support:

docker info
docker buildx version
docker compose version
docker run --rm alpine:3.22 echo "Container running inside the sandbox"

You should see Docker server information, plugin versions, and Container running inside the sandbox. You can then run docker build or docker compose commands against your project from the same terminal.

Update the Template

Publish a new tag, such as docker-v2, and update Template in the workspace spec. Create a new workspace to use the new image; editing the spec does not replace an existing workspace's environment. Commit and push any changes you want to keep before deleting an old workspace.