Docker Sandbox

The Docker sandbox provider provisions agent sessions as Docker containers using the dockerode library. Each session runs in an isolated container that self-registers with the platform, clones the repository, installs kit toolchains in-box, and runs the agent loop. The container auto-removes on exit.

How Docker sessions work

When the platform dispatches a session to a docker pool, DockerSandboxProvider.provision():

Connects to the Docker daemon (via DOCKER_HOST or the pool's dockerHost config key).
Pulls the worker image if not already cached locally.
Creates and starts a container with the registration token and injected env vars.
Returns a SandboxHandle with the container ID.

The container runs ghcr.io/renseiai/donmai-worker:latest by default. This image bakes the donmai binary and sets donmai agent run as its ENTRYPOINT. The runner self-registers, polls for work, clones the repo, installs kits in-box, and runs the agent - no separate docker exec call is needed.

Capability profile

Capability	Value
`transportModel`	`either` (dial-in exec or dial-out via token)
`supportsFsSnapshot`	false
`supportsPauseResume`	false
`supportsCapacityQuery`	true (`docker info` + host cgroup stats)
`maxConcurrent`	null (host-limited)
`maxSessionDurationSeconds`	null (no platform ceiling)
`os`	linux, macOS
`arch`	x86_64, arm64
`idleCostModel`	zero (your own hardware)
`billingModel`	fixed
`supportsGpu`	false (requires nvidia-container-toolkit on the host)
`supportsCustomNetworkPolicy`	true (Docker network modes and iptables)
`egressDefault`	allow-all

Substrate defaults

Docker pools satisfy all substrate requirements that use the donmai worker image:

Runtime kinds: native, npm, python-pip, http, mcp-server, a2a-protocol, workarea
Requirement kinds: persistent-storage, long-running, workarea, network-egress, git, full-history-clone, toolchain:go, toolchain:node

Note: host-binary is not a Docker class default - agents that require host-installed binaries must use the local provider.

Prerequisites

Docker Engine running and accessible on the host running the Rensei platform service.
The platform host must be able to reach the Docker socket or TCP endpoint.
The worker image ghcr.io/renseiai/donmai-worker:latest must be pullable from the pool host. The platform attempts a pull before every container start; pull failures fall back to using a locally cached image.

Container labels

Every container provisioned by the Docker provider is labelled:

rensei.project-id: <projectId>
rensei.org-id: <orgId>
rensei.managed-by: rensei-platform

These labels make it easy to find and audit platform-managed containers:

docker ps --filter "label=rensei.managed-by=rensei-platform"

Pool configuration

Create a Docker pool at Settings → Execution → Capacity → New pool → Docker.

Config key	Type	Default	Description
`dockerHost`	string	`DOCKER_HOST` env or `/var/run/docker.sock`	Docker daemon endpoint. Use `unix:///var/run/docker.sock` or `tcp://host:2375`.
`image`	string	`ghcr.io/renseiai/donmai-worker:latest`	Worker container image
`memoryMB`	number	`2048`	Memory limit per container in MiB
`cpu`	string	`"1.0"`	CPU quota (NanoCPUs: 1.0 = one full CPU core)

Example pool config

{
  "dockerHost": "tcp://build-host.internal:2375",
  "image": "ghcr.io/renseiai/donmai-worker:v0.11.0",
  "memoryMB": 4096,
  "cpu": "2.0"
}

Resource limits

Resource limits are applied at container creation via Docker's HostConfig:

Memory: memoryMB * 1024 * 1024 bytes
NanoCpus: cpu * 1e9

The container uses AutoRemove: true, so it cleans up automatically when the session completes or the agent exits. Manual termination calls container.stop({ t: 10 }) followed by container.remove({ force: true }).

Log streaming

The Docker provider implements streamLogs by following the container's stdout/stderr via the Docker API. Logs are multiplexed with 8-byte Docker stream headers and yielded as raw UTF-8 chunks to the session detail view.

Network policy

Docker network policy is configured at the Docker daemon level (bridge networks, custom networks, iptables rules). The platform does not configure network policy on individual containers beyond what the dockerHost daemon provides. To enforce egress restrictions:

Create a custom Docker network with restricted egress.
Reference it in your pool config or Docker daemon default network settings.

Custom worker image

To use a custom image (for example, one with additional system packages):

Start from ghcr.io/renseiai/donmai-worker:latest as the base.
Add your packages.
Do not override the ENTRYPOINT - it must remain donmai agent run.
Push the image to a registry accessible from your Docker host.
Set config.image on the pool.

FROM ghcr.io/renseiai/donmai-worker:latest
RUN apt-get install -y ffmpeg jq
# ENTRYPOINT is inherited - do not override it

Capacity Pools - pool management and substrate resolution
Add a Provider - SandboxProvider interface
Kubernetes - cluster-based alternative for larger fleets
Local - host-managed daemon workers

On this page