Run Docker inside a sandbox

Sandboxes run inside gVisor (runsc). Docker is not installed automatically — you install it yourself after the sandbox is ready, then start dockerd with a small bootstrap script so nested containers work.

When to use this recipe

Spinning up Postgres, Redis, or other services with docker compose during a test run.
Letting an agent build and run containers without host Docker access.
Prototyping a multi-service setup in a disposable environment.

Prerequisites

A Brimble account with sandbox access and BRIMBLE_SANDBOX_KEY set.
The SDK installed (see SDKs).
Outbound network for pulling packages and images (egress.mode defaults to open).
A Debian/Ubuntu template such as ubuntu-24, node-22, or python-3.12 (images must have apt).
1 GB+ RAM recommended (specs.memory: 1024 or higher).

Why a custom `dockerd` startup?

A plain apt install docker.io plus default dockerd often fails inside gVisor with overlay mount errors. Use a startup script that:

Mounts tmpfs on /var/lib/docker — avoids overlay: invalid argument when pulling and running images.
Runs dockerd with --iptables=false and --ip6tables=false — Docker does not manage iptables inside the sandbox; you set SNAT manually instead.
Passes --feature containerd-snapshotter=false on Docker ≥ 29 — the default containerd snapshotter does not work in gVisor; the legacy storage path does.

Save this as start-dockerd.sh inside the sandbox (for example under /usr/local/bin/):

start-dockerd.sh

#!/bin/bash
set -xe -o pipefail

USE_OVERLAY_DRIVER=true
while [[ $# -gt 0 ]]; do
  case $1 in
    --no-overlay)
      USE_OVERLAY_DRIVER=false
      shift
      ;;
    *)
      shift
      ;;
  esac
done

if [[ "${USE_OVERLAY_DRIVER}" == "true" ]]; then
  current_fs=$(stat -f -c %T /var/lib/docker 2>/dev/null || echo "none")
  if [[ "${current_fs}" != "tmpfs" ]]; then
    mkdir -p /var/lib/docker
    mount -t tmpfs -o size="${DOCKER_TMPFS_SIZE:-512M}" tmpfs /var/lib/docker
  fi
fi

EXTRA_DOCKERD_FLAGS=()
docker_version=$(dockerd --version)
if [[ ${docker_version} =~ version\ ([0-9]+) ]] && [[ ${BASH_REMATCH[1]} -ge 29 ]]; then
  EXTRA_DOCKERD_FLAGS+=(--feature containerd-snapshotter=false)
fi

dev=$(ip route show default | sed 's/.* dev \([^ ]*\) .*/\1/')
addr=$(ip addr show dev "$dev" | grep -w inet | sed 's/^\s*inet \([^/]*\)\/.*$/\1/')

echo 1 > /proc/sys/net/ipv4/ip_forward
iptables-legacy -t nat -A POSTROUTING -o "$dev" -j SNAT --to-source "$addr" -p tcp
iptables-legacy -t nat -A POSTROUTING -o "$dev" -j SNAT --to-source "$addr" -p udp

exec dockerd --iptables=false --ip6tables=false "${EXTRA_DOCKERD_FLAGS[@]}"

Recipe

Create a sandbox, install Docker, upload the script, start the daemon, then run a container.

import { Sandbox } from "@brimble/sandbox";
import { readFileSync } from "node:fs";

const client = new Sandbox();

const handle = await client.sandboxes.create({
  region: "auto",
  template: "ubuntu-24",
  specs: { cpu: 500, memory: 1024 },
  egress: { mode: "open" },
});

try {
  const install = await handle.exec({
    cmd: "export DEBIAN_FRONTEND=noninteractive && apt-get update -qq && apt-get install -y docker.io iptables",
    timeout_seconds: 300,
  });
  if (install.exit_code !== 0) throw new Error(install.stderr || install.stdout);

  await handle.putFile(
    "/usr/local/bin/start-dockerd.sh",
    readFileSync("./start-dockerd.sh"),
  );

  const start = await handle.exec({
    cmd: "chmod +x /usr/local/bin/start-dockerd.sh && DOCKER_TMPFS_SIZE=512M nohup /usr/local/bin/start-dockerd.sh >/tmp/dockerd.log 2>&1 & sleep 12 && docker info >/dev/null",
    timeout_seconds: 120,
  });
  if (start.exit_code !== 0) throw new Error(start.stderr || start.stdout);

  const hello = await handle.exec({
    cmd: "docker run --rm hello-world",
    timeout_seconds: 300,
  });
  console.log(hello.stdout);
} finally {
  await handle.destroy();
}

from pathlib import Path

from brimble_sandbox import Sandbox

client = Sandbox()

handle = client.sandboxes.create({
    "region": "auto",
    "template": "ubuntu-24",
    "specs": {"cpu": 500, "memory": 1024},
    "egress": {"mode": "open"},
})

try:
    install = handle.exec({
        "cmd": "export DEBIAN_FRONTEND=noninteractive && apt-get update -qq && apt-get install -y docker.io iptables",
        "timeout_seconds": 300,
    })
    if install["exit_code"] != 0:
        raise RuntimeError(install.get("stderr") or install.get("stdout"))

    handle.put_file(
        "/usr/local/bin/start-dockerd.sh",
        Path("start-dockerd.sh").read_bytes(),
    )

    start = handle.exec({
        "cmd": "chmod +x /usr/local/bin/start-dockerd.sh && DOCKER_TMPFS_SIZE=512M nohup /usr/local/bin/start-dockerd.sh >/tmp/dockerd.log 2>&1 & sleep 12 && docker info >/dev/null",
        "timeout_seconds": 120,
    })
    if start["exit_code"] != 0:
        raise RuntimeError(start.get("stderr") or start.get("stdout"))

    hello = handle.exec({
        "cmd": "docker run --rm hello-world",
        "timeout_seconds": 300,
    })
    print(hello["stdout"])
finally:
    handle.destroy()

package main

import (
	"context"
	"fmt"
	"os"

	sandbox "github.com/brimblehq/brimble-sdks/sandbox-go"
)

func main() {
	ctx := context.Background()
	client, _ := sandbox.NewClient(sandbox.ClientConfig{})

	memory := 1024
	handle, _ := client.Sandboxes.Create(ctx, sandbox.CreateSandboxRequest{
		Region:   "auto",
		Template: "ubuntu-24",
		Specs:    &sandbox.SandboxSpecs{CPU: 500, Memory: &memory},
		Egress:   &sandbox.SandboxEgressConfig{Mode: sandbox.SandboxEgressModeOpen},
	})
	defer handle.Destroy(ctx)

	install, _ := handle.Exec(ctx, sandbox.ExecInput{
		Cmd:            "export DEBIAN_FRONTEND=noninteractive && apt-get update -qq && apt-get install -y docker.io iptables",
		TimeoutSeconds: 300,
	})
	if install.ExitCode != 0 {
		panic(install.Stderr)
	}

	body, _ := os.ReadFile("start-dockerd.sh")
	_, _ = handle.PutFiles(ctx, []sandbox.BatchFileUploadItem{{
		Path:    "/usr/local/bin/start-dockerd.sh",
		Content: body,
	}})

	start, _ := handle.Exec(ctx, sandbox.ExecInput{
		Cmd:            "chmod +x /usr/local/bin/start-dockerd.sh && DOCKER_TMPFS_SIZE=512M nohup /usr/local/bin/start-dockerd.sh >/tmp/dockerd.log 2>&1 & sleep 12 && docker info >/dev/null",
		TimeoutSeconds: 120,
	})
	if start.ExitCode != 0 {
		panic(start.Stderr)
	}

	result, _ := handle.Exec(ctx, sandbox.ExecInput{
		Cmd:            "docker run --rm hello-world",
		TimeoutSeconds: 300,
	})
	fmt.Println(result.Stdout)
}

exec requests accept timeout_seconds between 1 and 300. Split long apt-get runs or re-run install if needed.

Without uploading a file

You can inline the same steps with shell exec if you prefer not to upload start-dockerd.sh:

export DEBIAN_FRONTEND=noninteractive
apt-get update -qq && apt-get install -y docker.io iptables
# paste start-dockerd.sh to /usr/local/bin/start-dockerd.sh, then:
chmod +x /usr/local/bin/start-dockerd.sh
DOCKER_TMPFS_SIZE=512M nohup /usr/local/bin/start-dockerd.sh >/tmp/dockerd.log 2>&1 &
sleep 12 && docker info && docker run --rm hello-world

What’s happening

create. Blocks until the sandbox VM is ready (gVisor container running, no Docker yet).
apt-get install docker.io. Installs the Docker engine and CLI on Debian/Ubuntu.
start-dockerd.sh. Mounts tmpfs on /var/lib/docker, configures SNAT for outbound traffic, and starts dockerd --iptables=false --ip6tables=false with --feature containerd-snapshotter=false when Docker is version 29 or newer.
docker run. Talks to the local daemon over /var/run/docker.sock inside the sandbox.
--network=host. Port mapping via -p is not supported inside sandboxes — bind on the host network instead when exposing services.

If you pause and resume a sandbox, reinstall Docker and restart dockerd — the daemon does not persist across resume.

Limitations

Template OS: agent-only images (for example codex, bun-1) may not have apt; use ubuntu-24, node-22, or python-3.12.
Port mapping: use --network=host, not -p / --expose.
Install time: first apt-get install can take several minutes; use the maximum timeout_seconds (300) per exec call.
Performance: nested containers are slower than running Docker on a bare VM.
Resume: after pause/resume, run the install and start-dockerd.sh steps again.

Next steps

Run untrusted code — deny egress and run a single snippet instead.
Run an AI coding agent — combine Docker with an agent workflow.
Network egress — restrict outbound access when pulling images from private registries.
Sandboxes overview — lifecycle, billing, and network egress.

Getting started

Brimble Agent

Brimble MCP

Projects

Sandboxes

Volumes

Object storage

Domains

Environments

Networking

Scaling

Observability

Analytics

Workspaces and teams

Security

Billing

Notifications

Webhooks

Log Drains

Troubleshooting

Reference

Run Docker inside a sandbox

When to use this recipe

Prerequisites

Why a custom `dockerd` startup?

Recipe

Without uploading a file

What’s happening

Limitations

Next steps

​When to use this recipe

​Prerequisites

​Why a custom dockerd startup?

​Recipe

​Without uploading a file

​What’s happening

​Limitations

​Next steps

When to use this recipe

Prerequisites

Why a custom `dockerd` startup?

Recipe

Without uploading a file

What’s happening

Limitations

Next steps