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 512The 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).stateReasonsays 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 saysclaimed … 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 endfailed, 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 /workspacePaths 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 (
restartscounts it; processes and/tmpare gone); - it is not durable storage: if the host is replaced, the sandbox becomes
lostand 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:writecurl -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, eachEXECwith 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
claimedFromStandbyAtfor 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-Timingresponse header (auth,image,place,start,waitin milliseconds).
Your own image
dcloud sandbox sandboxes create --image python-data:2026-11 --memory-mb 1024image 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'sSTARTEDline says which entrypoint was not run; - not its
USER: commands always run as the unprivileged sandbox user (uid 65534), in/workspace, withHOME=/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 onecold. 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.
networknoneoropen; 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.poolsservice 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
minandmax. 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,
sizestays belowdesiredSizeandreasonsaysroom for 7 of 12 on …. - The pool shows
autoscale,desiredSize,reason(in words) andobserved(peak10s,steadyPerMin,refillMs,coldStarts15m,clampedAtMax).clampedAtMaxand cold starts are the signal to raisemax. Every change is a line in the pool's log (Monitoring logs, resource typesandbox-pool) and aSandbox Pool Scaledevent on your default event bus. - While autoscale is on,
sizeis the platform's: aPATCHofsizeanswers 409.autoscale: nullturns it off and leaves the current size as yours. Every warm instance is billed.
Terminal
dcloud sandbox shell sbx-0123456789abAn 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 browserThe 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 openreturns a link with one: the first request trades it for a cookie on that address and drops it from the URL. A program sendsAuthorization: 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.