Sandboxes

Isolated Linux sessions for agents and code interpreters: exec, files, network policy (private beta).

Preview — request access from the console.

A sandbox is an isolated Linux session you run commands in and move files in and out of. It is made for agents and code interpreters: an LLM writes Python, the sandbox runs it, the result comes back as output or as a file. A sandbox keeps running between commands, so state carries over: installed packages, files in /workspace, background processes.

Every sandbox runs in its own gVisor sandbox (a kernel in user space), as an unprivileged user, on a read-only root file system, in its own network namespace. Its hosts serve only your organization: sandboxes of other customers never share a machine with yours.

Private beta. Sandboxes are switched on per organization by an operator. Without that, the service does not appear in the console and its API answers 404.

Start one

dcloud sandbox sandboxes create --runtime python3.12 --memory-mb 512

The answer carries the sandbox's id (sbx-…) and its state:

  • running — commands go in now. A sandbox starts in about 0.2 s on a host that is already up.
  • pending — your organization needs a new sandbox host and none was ready: it waits for one to boot (about 40 s). stateReason says so. Read it again (dcloud sandbox sandboxes get --id …) until it runs. Usually there is one ready: the platform keeps a standby host booted in each region, never used by anyone. The create that needs a host (your first, or one your hosts have no room for) claims it on the spot; from then on it is your organization's host only, as every sandbox host is. The sandbox's log says claimed … from the standby hosts. The first sandbox on it waits only for its image to be pulled (about 6 s for 400 MB). The creates of a burst that come after it land on the same host, and the host starts pulling your other images at once: those of your warm pools, then those your running sandboxes use (up to three), so the next create of one of them does not wait for the pull. When no standby host is left, a new host boots from a prebuilt image with everything installed (about 10 s after the server runs).
  • If the host chosen for it turns it down for lack of memory (the host enforces what each sandbox reserves, and in a rare race it can disagree with the placement), the sandbox is not failed: it is placed again on another of your hosts, a standby host, or waits for a new one. Its log says <host> refused it (no capacity: it holds X of Y MB), re-placed on <host>. Only when a second host turns it down too does it end failed, naming both.
Field Default Range
runtime python3.12 python3.12, nodejs22 (the stock Debian-slim images)
image — an image of your registry instead of runtime (see below)
ports — ports to expose at once (see Port URLs)
memoryMb 512 256–4096
vcpu memory/1 GB 0.5–4 (at least 0.5)
diskMb 2048 512–10240 — the size of /workspace; writes beyond it fail
timeoutSeconds 3600 60–86400; extend it with update
idleTimeoutSeconds 900 0 (off) or 60–86400: ends after that long without a command or file call
network none see below

An organization runs at most 20 sandboxes per region by default (forks included): the sandbox.active-sandboxes service quota, which can be raised under Service quotas.

Run commands

dcloud sandbox sandboxes exec --id sbx-0123456789ab --command 'python3 -c "print(6*7)"'

cmd is the program and its arguments (["python3", "-c", "print(1)"]); command is a shell line, run as sh -c. Commands run as an unprivileged user in /workspace, with a timeout (timeoutMs, default 60 s, at most 30 minutes). The answer is exitCode, stdout, stderr and durationMs. Through the API the output is cut to 256 KB per stream (head and tail kept, truncated: true). A command takes about 10 ms on the host plus the round trip.

Move files

dcloud sandbox files write --id sbx-… --path /workspace/data.csv --content @data.csv
dcloud sandbox sandboxes exec --id sbx-… --command 'python3 analyse.py data.csv > out.txt'
dcloud sandbox files read  --id sbx-… --path /workspace/out.txt
dcloud sandbox files list  --id sbx-… --path /workspace

Paths are inside /workspace; .. and symlinks are refused. Text comes back as content, binary files as contentBase64. Through the API a file is at most 10 MB; the data plane (below) takes 100 MB per file.

/workspace is a file system of its own, diskMb large. It lives on the sandbox host's disk:

  • it survives a restart of the host or of its daemon — the sandbox is started again with the same id and the same files (restarts counts it; processes and /tmp are gone);
  • it is not durable storage: if the host is replaced, the sandbox becomes lost and its files with it. Copy out what you need to keep.

Network

network.mode What the sandbox can reach
none Nothing. Default.
allowlist Only the names in allow, on TCP 80 and 443. allow holds host names (pypi.org), suffixes (.github.com: the name and everything under it) and presets
open The internet. Needs sandbox:UseOpenEgress
{ "network": { "mode": "allowlist", "allow": ["package-registries", "api.example.com"] } }

The preset package-registries covers PyPI, npm, crates.io, the Go proxy, Debian, Ubuntu and Alpine mirrors, Maven Central, Anaconda, GitHub and GitLab: what pip install, npm install, go get and git clone need. Stock images carry no data libraries (no pandas, no numpy); install them through this preset.

How the allow-list works: the sandbox's only resolver is the host's filtering resolver. It answers only allowed names — anything else is answered "does not exist", never forwarded, and logged — and opens the addresses it answered, for their DNS lifetime, to that sandbox alone. A connection to any other address is refused. Residual: an address opened for an allowed name may serve other names too (shared CDNs); the allow-list does not inspect TLS. Every mode refuses private and link-local ranges, the cloud metadata service, the platform's control plane and SMTP ports. There is no IPv6.

The data plane: lower latency, bigger files

connect mints a token (15 minutes by default, at most an hour and never beyond the sandbox) for the sandbox host's own HTTPS API:

dcloud sandbox sandboxes connect --id sbx-… --scopes exec --scopes files:read --scopes files:write
curl -H "Authorization: Bearer $TOKEN" -d '{"cmd":["python3","-c","print(1)"]}' "$URL/exec"
curl -H "Authorization: Bearer $TOKEN" -T big.parquet "$URL/files?path=/workspace/big.parquet"
curl -H "Authorization: Bearer $TOKEN" -o out.csv "$URL/files?path=/workspace/out.csv"
curl -H "Authorization: Bearer $TOKEN" "$URL/files/list?path=/workspace"

Each scope needs the matching permission (ExecCommand, ReadFiles, WriteFiles), checked when the token is minted. A token opens one sandbox; when the sandbox ends, its token opens nothing.

Fork

dcloud sandbox sandboxes fork --id sbx-…

copies a running sandbox — memory, running processes, /tmp and /workspace — into a new sandbox that continues from there, on the same host, with the same size and network, and a fresh lifetime. It counts against the quota.

IAM and audit

Action What it allows
DescribeSandboxes List and read sandboxes and your sandbox hosts
CreateSandbox Start one
UpdateSandbox Extend its lifetime, change its idle timeout or metadata
TerminateSandbox Stop it
ForkSandbox Copy it (with CreateSandbox)
UseOpenEgress network.mode: open
ExecCommand Run commands
ReadFiles Download files (sensitive: what the code computed)
WriteFiles Upload files
GetSandboxLogs Read its log (sensitive: command lines)
ConnectSandbox Mint a data-plane token, or a link to a private port
StartTerminal Open a terminal (with ConnectSandbox)
ExposePort Expose a port (private) or close it
ExposePublicPort Expose a port publicly
DescribePools List and read warm pools
CreatePool Create a warm pool
UpdatePool Resize a pool or move it to another image
DeletePool Delete a pool

An image needs ecr:PullImage on its repository too, when the sandbox or pool is created. A pool is rn:ews:de1:<org>:sandbox:pool/<id>.

The resource is rn:ews:de1:<org>:sandbox:sandbox/<id>. Every call through the API is authorized and written to the audit log, reads of files included. On the data plane the mint is audited and every command and file transfer goes to the sandbox's log. A useful policy for an agent's access key: CreateSandbox, ExecCommand, ReadFiles, WriteFiles, TerminateSandbox — and no UseOpenEgress.

What you see

  • The sandbox: where it runs (its host, the server type and location), the runtime image's digest, its deadlines, how many commands ran, how often it was re-created after a host restart, and, once ended, why (deleted, ttl, idle, failed, capacity, lost) and what it used (vCPU-seconds, GiB-seconds).
  • The log (dcloud sandbox sandboxes logs --id …): STARTED/RESTARTED/STOPPED, each EXEC with its exit code and duration, each file read and write with its size, and every DNS lookup an allow-list refused.
  • Your sandbox hosts: state, size, memory reserved, what the daemon reports as wrong, and claimedFromStandbyAt for a host your organization took from the standby hosts. Host time is counted for your organization from that moment, never before.
  • Where a create's time went: the create's Server-Timing response header (auth, image, place, start, wait in milliseconds).

Your own image

dcloud sandbox sandboxes create --image python-data:2026-11 --memory-mb 1024

image takes an image of your organization's registry: repo:tag, repo@sha256:…, or either with your registry host in front. It is pinned to its digest when the sandbox is created (needs ecr:PullImage on the repository, audited), so a tag moved later does not change a running sandbox. The sandbox's host pulls it once, with a token for that one repository, and checks every layer against its digest.

What a sandbox takes from the image, and what it does not:

  • its files (read-only) and its environment (ENV, PATH): every command sees them;
  • not its ENTRYPOINT/CMD: a sandbox runs the commands you send. The log's STARTED line says which entrypoint was not run;
  • not its USER: commands always run as the unprivileged sandbox user (uid 65534), in /workspace, with HOME=/tmp;
  • it needs /bin/sh. An image without it fails to start with that reason.

Images up to 4 GB uncompressed, linux/amd64. The first sandbox of an image on a host waits for the pull (the create answers pending, the sandbox starts when the pull is done); later ones start from the host's copy. A warm pool (below) pulls ahead.

Warm pools: start in milliseconds

A warm pool keeps sandboxes of one image and size started on your sandbox host. A create that asks for the same image (or runtime), memoryMb, vcpu, diskMb and network mode claims one: the host hands over a sandbox that is already up, workspace mounted, network policy applied.

dcloud sandbox pools create --name python-data --image python-data:2026-11 --memory-mb 512 --size 5
dcloud sandbox sandboxes create --image python-data:2026-11 --memory-mb 512   # startMode: pool
  • A claimed sandbox reports startMode: pool, a fresh one cold. The pool refills in the background; when it is empty a create starts cold, it does not wait.
  • Warm instances reserve memory on your host (a host boots for the pool if you have none) and are billed like running sandboxes while warm.
  • network none or open; an allow-list sandbox always starts cold. Changing the pool's image replaces its warm instances.
  • At most 3 pools per region by default (the sandbox.pools service quota), of 10 instances each.

Autoscaling on claim rate

Give a pool autoscale: {min, max} instead of (or with) a size, and the platform sizes it every minute from the creates that matched it in the last 15 minutes — those that claimed one and those that found it empty and started cold:

dcloud sandbox pools create --name python-data --image python-data:2026-11 --memory-mb 512 \
  --autoscale '{"min":1,"max":10}'
  • Size = the most matching creates within any 10 s (a burst of N needs N already warm), or the steady rate × the pool's refill time × 2 if that is more, between min and max. It grows in one step and shrinks by at most half per minute, so a second burst soon after still finds some warm.
  • It only takes free memory on the pool's host: it never boots a host or pushes a sandbox out. When the host has no room, size stays below desiredSize and reason says room for 7 of 12 on ….
  • The pool shows autoscale, desiredSize, reason (in words) and observed (peak10s, steadyPerMin, refillMs, coldStarts15m, clampedAtMax). clampedAtMax and cold starts are the signal to raise max. Every change is a line in the pool's log (Monitoring logs, resource type sandbox-pool) and a Sandbox Pool Scaled event on your default event bus.
  • While autoscale is on, size is the platform's: a PATCH of size answers 409. autoscale: null turns it off and leaves the current size as yours. Every warm instance is billed.

Terminal

dcloud sandbox shell sbx-0123456789ab

An interactive shell (bash if the image has it, else sh) on a real pseudo-terminal, in /workspace, as the sandbox user: editors, top, ^C, window resizes work. In the console: Open terminal on the sandbox.

Under the hood: connect with the scope terminal (needs sandbox:StartTerminal, audited), then a WebSocket straight to the sandbox's host, wss://<host>/v1/sessions/<id>/pty, with the subprotocols ews.terminal and ews.token.<token>. Binary frames carry keystrokes and output; a text frame {"type":"resize","cols":120,"rows":40} resizes; the host sends {"type":"exit","code":0} before it closes.

The sandbox log records that a terminal was opened and closed, how long and how many bytes moved, not what was typed or printed. At most 4 terminals per sandbox; an open terminal keeps the sandbox from its idle timeout.

Port URLs

A server in a sandbox can get its own HTTPS address:

dcloud sandbox ports expose --id sbx-0123456789ab --port 8080          # private
dcloud sandbox ports open --id sbx-0123456789ab --port 8080            # a link for your browser

The address is https://8080-0123456789ab.sbx.apps.<root> — the port, then the sandbox id without sbx-. The sandbox's host forwards HTTP and WebSocket requests to the server listening on 0.0.0.0:8080 in the sandbox (502 with a short page while nothing listens). The name resolves within about 20 seconds of exposing.

  • private (default): a request needs a port token. ports open returns a link with one: the first request trades it for a cookie on that address and drops it from the URL. A program sends Authorization: Bearer <token>. The token opens that one port of that one sandbox, for up to an hour (ttlSeconds); minting it is audited (ConnectSandbox).
  • public: anyone with the address, at most 100 requests a second. Needs sandbox:ExposePublicPort.

Ports 1024–65535, at most 5 per sandbox; ports on create exposes them at once. A sandbox with network none still answers on its exposed ports: requests come in, nothing goes out. A request to a port counts as activity for the idle timeout.

Billing

SKU Price (indicative) On
sandbox.vcpu_hour €0.040 per vCPU-h allocated vCPU while a sandbox runs or a pool keeps warm
sandbox.gib_hour €0.012 per GiB-h allocated memory, the same way

Metered per sandbox and clock hour (and per pool, from the instances actually warm), shown in the cost explorer as "preview, not charged": the amount is €0 while the service is in preview. Workspace disk is not billed in the preview.

Limits and what is not there yet

  • Sandboxes run under gVisor on Hetzner Cloud VMs. Firecracker microVMs on bare metal come later behind the same API.
  • Commands always run as uid 65534: an image that must run as root does not work as is.
  • No streaming output for exec (use the terminal), no workspace snapshots (a sandbox's files live as long as it does).
  • An operator can raise the sandbox host limit for one organization; sandboxes and pools are service quotas.
Did this page help you?