Sandboxes

This creates a sandbox named web, then stops it. A stopped sandbox keeps its files, and a start runs it again. The Processes routes run commands in it:

curl --unix-socket /var/lib/shard/shard.sock -X POST -H 'Content-Type: application/json' -d '{"name":"web","image":"alpine:3.20","resources":{"memory_mib":512}}' 'http://localhost/v0/sandboxes?wait=true'
curl --unix-socket /var/lib/shard/shard.sock -X POST http://localhost/v0/sandboxes/web/stop
curl --unix-socket /var/lib/shard/shard.sock -X POST http://localhost/v0/sandboxes/web/start

Every {id} in a path takes a sandbox’s id or name. A create on vz or Firecracker with no resources.memory_mib gets 512 MiB, because a VM always needs a memory size. On gVisor, runc and Sysbox it has no bound.

Each route answers an error with the Error body, unless its responses say otherwise.

List active sandboxes

GET /v0/sandboxes · scope sandbox:read

Parameters

Name	In	Type	Required	Description
all	query	boolean	no	List stopped sandboxes too.
limit	query	integer (int64)	no	The most items on a page; absent returns the whole list. At least 1.
cursor	query	string	no	The next value of the previous page; this page starts after it.

Responses

Status	Body
200	SandboxesResponse as application/json

Read a sandbox and the egress rules the host enforces for it

GET /v0/sandboxes/{id} · scope sandbox:read

Parameters

Name	In	Type	Required	Description
id	path	string	yes
wait	query	boolean	no	Wait until a pending create finishes, then answer.

Responses

Status	Body
200	Inspection as application/json

Create a sandbox

POST /v0/sandboxes · scope sandbox:write

A create that names secrets also needs the secret:* scope, one that names a policy needs policy:*, and one that forwards ports needs port:write; without it the answer is 403 forbidden.

Parameters

Name	In	Type	Required	Description
wait	query	boolean	no	Answer once the sandbox leaves pending; with Accept: application/x-ndjson the pull streams first.

Request body

CreateRequest as application/json, required.

Responses

Status	Body	Description
201	Sandbox as application/json, or CreateLine as application/x-ndjson	The sandbox, or with wait and Accept: application/x-ndjson one CreateLine per pull event and then the sandbox. An error after the first line ends the stream with a CreateLine whose error is set, and no sandbox.

Start a stopped sandbox with its saved files

POST /v0/sandboxes/{id}/start · scope sandbox:write

Parameters

Name	In	Type	Required	Description
id	path	string	yes	The sandbox id or name.

Responses

Status	Body
200	Sandbox as application/json

Stop a sandbox and preserve its files

POST /v0/sandboxes/{id}/stop · scope sandbox:write

Parameters

Name	In	Type	Required	Description
id	path	string	yes	The sandbox id or name.

Request body

StopRequest as application/json, optional.

Responses

Status	Body
200	Sandbox as application/json

Remove a sandbox and its files

DELETE /v0/sandboxes/{id} · scope sandbox:delete

Parameters

Name	In	Type	Required	Description
id	path	string	yes
force	query	boolean	no	Stop the sandbox first if it is running or paused.

Responses

Status	Body
204	none

Save a sandbox’s state and suspend it

POST /v0/sandboxes/{id}/pause · scope sandbox:write

Parameters

Name	In	Type	Required	Description
id	path	string	yes	The sandbox id or name.

Responses

Status	Body
200	Sandbox as application/json

Resume a paused sandbox from its saved state

POST /v0/sandboxes/{id}/resume · scope sandbox:write

Parameters

Name	In	Type	Required	Description
id	path	string	yes	The sandbox id or name.

Responses

Status	Body
200	Sandbox as application/json

Create a sandbox from a running sandbox’s memory and files

POST /v0/sandboxes/{id}/fork · scope sandbox:write

Parameters

Name	In	Type	Required	Description
id	path	string	yes	The sandbox id or name.

Request body

CopyRequest as application/json, optional.

Responses

Status	Body
201	Sandbox as application/json

Read or follow the egress decisions of a sandbox

GET /v0/sandboxes/{id}/egress-log · scope sandbox:read

Parameters

Name	In	Type	Required	Description
id	path	string	yes	The sandbox id or name.
follow	query	boolean	no	Keep the stream open until the sandbox stops or is removed; a WebSocket upgrade requires follow=true.

Responses

Status	Body	Description
101	WebSocket	A WebSocket follow with follow=true: one egress decision per text message, until the sandbox stops, fails or is removed.
200	array of EgressDecision as application/json, or EgressDecision as application/x-ndjson	The egress decisions, oldest first; with follow one decision per line until the sandbox stops, fails or is removed.

Response headers

Header	Status	Type	Description
Shard-Egress-Cut	200	integer	The older decisions the read left out; absent when it left out none.

Grant a secret to a sandbox

POST /v0/sandboxes/{id}/secrets/{name} · scope secret:*

Parameters

Name	In	Type	Required
id	path	string	yes
name	path	string	yes

Responses

Status	Body
200	Sandbox as application/json

Ungrant a secret from a sandbox

DELETE /v0/sandboxes/{id}/secrets/{name} · scope secret:*

Parameters

Name	In	Type	Required
id	path	string	yes
name	path	string	yes

Responses

Status	Body
200	Sandbox as application/json

Attach a policy to a sandbox

PUT /v0/sandboxes/{id}/policy · scope policy:*

Parameters

Name	In	Type	Required	Description
id	path	string	yes	The sandbox id or name.

Request body

PolicyAttachRequest as application/json, required.

Responses

Status	Body
200	Sandbox as application/json

Detach the policy of a sandbox

DELETE /v0/sandboxes/{id}/policy · scope policy:*

Parameters

Name	In	Type	Required	Description
id	path	string	yes	The sandbox id or name.

Responses

Status	Body
200	Sandbox as application/json

Objects

CopyRequest

Field	Type	Required
name	string	no

CreateLine

Field	Type	Required
error	ErrorObject	no
event	Event	no
sandbox	Sandbox	no

CreateRequest

Field	Type	Required	Description
env	array of string	no
image	string	no	The image to create from. A create names exactly one of image and snapshot.
name	string	no
policy	string	no
ports	array of PortForward	no
resources	ResourceRequest	no
secrets	array of string	no
snapshot	string	no	The snapshot id or name to create from. A create names exactly one of image and snapshot.
user	string	no
workdir	string	no

Destination

Field	Type	Required	Description
kind	string	yes	One of cidr, domain, domain-suffix, group.
value	string	yes

Effective

Field	Type	Required
missing	boolean	no
rules	array of EffectiveRule	yes

EffectiveRule

Field	Type	Required	Description
action	string	yes	One of allow, deny.
destination	Destination	yes
id	string	yes
implied	string	no	Set on a rule the policy did not write: dns when a name rule opened DNS, dns-rule when a dns rule did. One of dns, dns-rule.
ports	array of integer (int64)	no
protocol	string	no	Absent for a rule over every protocol. One of tcp, udp.

EgressDecision

Field	Type	Required	Description
address	string	no
host	string	no
port	integer (int64)	no
reason	string	no
rule	string	yes
rule_text	string	no
source	string	yes	One of proxy, host, dns.
time	string (date-time)	yes
verdict	string	yes	One of allow, deny.

Event

Field	Type	Required	Description
bytes	integer (int64)	no
digest	string	no
layer	integer (int64)	no
layers	integer (int64)	no
present	boolean	no
reference	string	no
status	string	yes	cached and pulled carry reference and digest; pulling adds layers and bytes, the whole download; layer carries one layer’s digest, bytes and present; unpacking carries reference, digest and layers; unpacked carries one layer’s digest, layer and layers; building carries nothing more. One of cached, pulling, layer, unpacking, unpacked, building, pulled.

ExitStatus

Field	Type	Required
code	integer (int64)	yes
signal	integer (int64)	yes

Inspection

Field	Type	Required	Description
created_at	string (date-time)	yes
digest	string	no
egress	Effective	no
failed_reason	string	no
forked_from	string	no
id	string	yes
image	string	yes
kernel	string	no
name	string	no
oom	OOM	no
policy	string	no
ports	array of PortForward	no
processes	array of Process	no
provider	string	yes
resources	Resources	yes
secrets	array of string	no
snapshot	string	no
started_at	string (date-time)	no
state	string	yes	One of pending, created, running, paused, unresponsive, stopped, failed.
stopped_reason	string	no

OOM

Field	Type	Required	Description
killed_at	string (date-time)	yes	When the host last ended the sandbox for its memory.
kills	integer (int64)	yes	Every time the host ended the sandbox for its memory. At least 1.
restart_at	string (date-time)	no	When the daemon starts the sandbox again; absent once a start ran or a stop called it off.

PolicyAttachRequest

Field	Type	Required	Description
policy	string	yes	At least 1 character.

PortForward

Field	Type	Required	Description
guest_port	integer (int32)	yes	The port on the sandbox’s 127.0.0.1 a connection goes to. From 1 to 65535.
host_port	integer (int32)	yes	The port on the host the forward listens on. From 1 to 65535.
public	boolean	no	Listen on 0.0.0.0, every interface of the host, instead of 127.0.0.1.

Process

Field	Type	Required
command	array of string	yes
env	array of string	no
killed	boolean	no
name	string	yes
restart	RestartSpec	yes
status	ProcessStatus	yes
user	string	no
workdir	string	no

ProcessStatus

Field	Type	Required	Description
exit	ExitStatus	no
restarts	integer (int64)	yes
started_at	string (date-time)	no
state	string	yes	One of running, restarting, exited, killed, gave-up, stopped.

ResourceRequest

Field	Type	Required	Description
disk_mib	integer (int64)	no	From 0 to 16777088.
memory_mib	integer (int64)	no	The memory bound in MiB. Absent, a create from a snapshot takes the snapshot’s bound. Otherwise absent or 0 is 512 on the firecracker and vz providers, and no bound on gvisor, runc and sysbox. From 0 to 16777216.
swap_mib	integer (int64)	no	The swap file in MiB, which the guest makes on its disk and which counts against disk_mib. Absent is 2048 on the firecracker and vz providers and none on gvisor, runc and sysbox, which refuse any swap but 0. From 0 to 16777088.
vcpus	integer (int64)	no	At least 0.

Resources

Field	Type	Required
disk_mib	integer (int64)	yes
memory_mib	integer (int64)	yes
swap_mib	integer (int64)	yes
vcpus	integer (int64)	yes

RestartSpec

Field	Type	Required	Description
backoff	integer (int64)	no	The first wait before a restart, in seconds; 0 or absent is 1. It doubles after each restart, up to 60. Only on-failure, always and unless-stopped take it. From 0 to 60.
policy	string	yes	One of no, on-failure, always, unless-stopped.
retries	integer (int64)	no	The restarts in a row before the policy gives up; 0 or absent is unlimited. Only on-failure takes it. At least 0.

Sandbox

Field	Type	Required	Description
created_at	string (date-time)	yes
digest	string	no
failed_reason	string	no
forked_from	string	no
id	string	yes
image	string	yes
kernel	string	no
name	string	no
oom	OOM	no
policy	string	no
ports	array of PortForward	no
processes	array of Process	no
provider	string	yes
resources	Resources	yes
secrets	array of string	no
snapshot	string	no
started_at	string (date-time)	no
state	string	yes	One of pending, created, running, paused, unresponsive, stopped, failed.
stopped_reason	string	no

SandboxesResponse

Field	Type	Required
next	string or null	yes
sandboxes	array of Sandbox	yes
warnings	array of string	no

StopRequest

Field	Type	Required