Skip to main content
Docker is the simplest sandbox provider for local development and trusted single-host self-hosting. Roomote starts one worker container per task, connects it to the configured Docker network, streams logs back to the task view, and stops the container when the task is finished.

​
When to use Docker

Use Docker when:
  • you are developing Roomote locally
  • you are trying Roomote on one trusted host
  • task volume is modest enough for the host machine
  • you want the fewest external sandbox accounts and credentials
Move to a hosted provider when multiple users run heavier tasks, when task work should not compete with the Roomote server, or when you need snapshot resume support.

​
Configuration

Docker does not need provider API credentials. Select Docker during setup or from Settings > Sandboxes. Common env vars: 
DEFAULT_COMPUTE_PROVIDER=docker
DOCKER_WORKER_IMAGE=roomote-worker:local
# Optional: defaults to the host architecture (linux/amd64 or linux/arm64)
DOCKER_WORKER_PLATFORM=linux/amd64
DOCKER_WORKER_NETWORK=roomote_worker
DOCKER_WORKER_RELEASE_PATH=/roomote/releases/worker-current.tar.gz
DOCKER_WORKER_CPU_LIMIT=2
DOCKER_WORKER_MEMORY_LIMIT=4g
DOCKER_WORKER_PIDS_LIMIT=512
DOCKER_WORKER_DISK_LIMIT=20g
DOCKER_WORKER_ALLOW_UNBOUNDED_DISK=false
DOCKER_WORKER_LOG_MAX_SIZE=10m
DOCKER_WORKER_LOG_MAX_FILES=3
# internet allows public egress but blocks private/metadata ranges
# none disables external egress entirely
DOCKER_WORKER_EGRESS_POLICY=internet
DOCKER_STANDBY_MAX_COUNT=10
DOCKER_STANDBY_MAX_AGE_HOURS=24
Local development builds roomote-worker:local automatically. Self-hosted Compose deployments normally use docker-compose.compute-docker.yml, which sets the worker image, platform, network, and release path for sibling worker containers. For production deployments, prefer an immutable registry-qualified worker image tag when workers need a published image instead of a local tag.

​
Resource and network isolation

Every Docker task receives a dedicated bridge network. In Compose deployments, Roomote attaches the API and, when enabled, the optional preview proxy to that network; sibling task containers and datastore containers are not reachable. The controller reconciles replacement API and preview-proxy containers onto running task networks, removes empty task networks periodically, and reaps stale provisioning containers after a restart. Workers default to 2 CPUs, 4 GiB of memory with no additional swap, 512 PIDs, a requested 20 GiB writable-layer quota, and three 10 MiB JSON log files. The variables above can tune those bounds. Writable-layer quotas require a Docker storage driver that supports --storage-opt size. When the driver rejects that option, Roomote refuses to start the task rather than allowing untrusted code to consume the host disk. Configure a quota-capable Docker data root. Operators that enforce an equivalent host-level quota can explicitly set DOCKER_WORKER_ALLOW_UNBOUNDED_DISK=true; Roomote then logs a warning and starts without --storage-opt size. Completed resumable tasks keep their stopped container and writable layer so a follow-up can restart the same workspace. Roomote retains at most 10 containers for 24 hours by default. Configure DOCKER_STANDBY_MAX_COUNT and DOCKER_STANDBY_MAX_AGE_HOURS to change those bounds; a count of 0 disables Docker standby retention. The five-minute retention sweep removes the oldest or expired containers and their task networks. These retention limits are also editable under Settings > Sandboxes > Local Docker > Advanced settings. Process environment variables take precedence and appear as locked values in Settings. The default internet egress policy allows public repository and tool access while installing immutable blackhole routes for private, shared-address, and cloud metadata ranges (including AWS/GCP/Azure, Alibaba, and Oracle endpoints). The task’s own, more-specific network route still reaches its API and preview proxy peers. In networked self-host deployments, direct connections to the Docker bridge gateway are also blocked without disrupting its use as the public-egress next hop. Local development blocks metadata ranges but retains private and gateway access because its API runs on the host. The worker never receives the network-administration capability needed to remove the policy. Set DOCKER_WORKER_EGRESS_POLICY=none for tasks that need only the Roomote API and preview proxy.

​
Security notes

Docker sandboxes require the Roomote controller to create and manage worker containers. Production Compose routes those operations through an internal socket proxy that allows only the container, exec, image, and network API sections Roomote needs; the controller does not mount the raw socket. Treat the proxy and Docker host as trusted infrastructure, and do not use Docker sandboxes as a multi-tenant isolation boundary for untrusted operators or repositories.

​
Verify setup

  1. select Docker as the sandbox provider
  2. start a small task from an environment
  3. confirm the task can clone the repository and run a simple command
  4. open task logs and verify output streams back to Roomote
  5. check that the worker container stops after the task completes

​
Common issues

  • The worker image is missing. Run the local dev server again, or publish and configure a worker image for self-hosted production.
  • The task cannot reach Roomote services. Check DOCKER_WORKER_NETWORK and the Compose network used by the API and controller.
  • A worker reports that its disk limit is unsupported. Configure a Docker storage driver with per-container writable-layer quota support. Only set DOCKER_WORKER_ALLOW_UNBOUNDED_DISK=true when an equivalent host-level quota is already enforced.