Docker in Sandboxes

A Daytona sandbox is a real virtual machine with its own kernel, so it can run a full Docker daemon inside — build images, run containers, use Compose. This is the natural fit for agents that need to execute docker commands, CI-style jobs, and testing containerized applications, all without giving anything access to a shared host daemon.

How it works

Docker's storage directory, /var/lib/docker, is backed by a dedicated ephemeral device attached to the sandbox, sized by the docker_data_mib parameter. Keeping Docker's data on its own device means container images and writable layers cannot eat into the sandbox's main filesystem (scratch_mib), and Docker gets a filesystem it is happy with regardless of your image.

There are two ways to enable the device:

1. Per sandbox — set docker_data_mib on the create request. This works with any image; you choose the size.
2. Per image — build a named project image with docker: true. Every sandbox created from it automatically gets the device at the default size of 10240 MiB (10 GiB). See Images.

Your image still needs Docker installed (e.g. docker.io / docker-ce packages) — the device gives the daemon a place to store data, it does not install Docker for you.

The device is ephemeral

The Docker data device is created fresh on every boot and is excluded from all snapshots — both disk and full — and from pause state. Concretely: pulled images, built layers, container filesystems, and named Docker volumes on the device do not survive a stop/start cycle, and are never captured when you snapshot the sandbox.

Note: Treat /var/lib/docker as a cache, never as storage. Persist anything valuable — build artifacts, images — by pushing to a registry or writing to a mounted volume or object store. Expect to re-pull base images after every boot.

Restrictions

A sandbox with a Docker data device cannot be paused or forked (v1) — those operations preserve state the ephemeral device fundamentally does not keep. Warm stop and start works fine for persistent sandboxes: the main filesystem survives, and the Docker device simply comes back empty.

Example

Create a sandbox with a 10 GiB Docker device and run a container inside it:

from rlp import Daytona, CreateSandboxFromImageParams
 
daytona = Daytona()
sandbox = daytona.create(CreateSandboxFromImageParams(
    image="my-docker-env",      # an image with Docker installed
    docker_data_mib=10240,      # 10 GiB for /var/lib/docker
))
 
result = sandbox.process.exec("docker run --rm hello-world")
print(result.result)

import { Daytona } from '@rlp/sdk'
 
const daytona = new Daytona()
const sandbox = await daytona.create({
  image: 'my-docker-env',   // an image with Docker installed
  dockerDataMib: 10240,     // 10 GiB for /var/lib/docker
})
 
const result = await sandbox.process.executeCommand('docker run --rm hello-world')
console.log(result.result)

curl -X POST https://api.rl.trydaytona.com/vms \
  -H "Authorization: Bearer $RLP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image": "my-docker-env", "docker_data_mib": 10240}'

If the image was built with docker: true, you can omit docker_data_mib entirely and every sandbox gets the 10 GiB device automatically — convenient when a whole fleet shares the same Docker-enabled environment.