Exec

This runs a command in the running sandbox web:

curl --unix-socket /var/lib/shard/shard.sock -X POST -H 'Content-Type: application/json' -d '{"command":["/bin/echo","hi"]}' http://localhost/v0/sandboxes/web/exec

The daemon answers 201 with the Exec. Routes with {exec} in the path use its exec field as the id. This one waits for the command to end:

curl --unix-socket /var/lib/shard/shard.sock 'http://localhost/v0/sandboxes/web/exec/<exec>?wait=true'

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

Execute a command in a running sandbox

POST /v0/sandboxes/{id}/exec · scope exec

Parameters

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

Request body

ExecRequest as application/json, required.

Responses

Status	Body
201	Exec as application/json

List the execs of a sandbox

GET /v0/sandboxes/{id}/exec · scope exec

Parameters

Name	In	Type	Required	Description
id	path	string	yes	The sandbox id or name.
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	ExecsResponse as application/json

Read, wait for or attach to an exec

GET /v0/sandboxes/{id}/exec/{exec} · scope exec

Parameters

Name	In	Type	Required	Description
id	path	string	yes	The sandbox id or name.
exec	path	string	yes	The exec id.
wait	query	boolean	no	Block until the exec ends.

Responses

Status	Body	Description
101	WebSocket	A WebSocket attach. Each binary message leads with its stream byte: 0 stdin and 4 stdin closed from the client; 1 stdout, 2 stderr, 3 the ExitMessage and 5 a FailureMessage from the daemon.
200	Exec as application/json	The exec as it stands, or with wait once it ends.

WebSocket messages

Stream byte	Payload
3	ExitMessage
5	FailureMessage

Send a signal to a running exec

POST /v0/sandboxes/{id}/exec/{exec}/kill · scope exec

Parameters

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

Request body

KillRequest as application/json, optional.

Responses

Status	Body
204	none

Forget an exec that ended

DELETE /v0/sandboxes/{id}/exec/{exec} · scope exec

Parameters

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

Responses

Status	Body
204	none

Resize the terminal of an exec

POST /v0/sandboxes/{id}/exec/{exec}/resize · scope exec

Parameters

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

Request body

TerminalSize as application/json, optional.

Responses

Status	Body
204	none

Objects

Exec

Field	Type	Required	Description
command	array of string	yes
exec	string	yes
exit_status	ExitStatus or null	yes
exited_at	string (date-time) or null	yes
lost_bytes	integer (int64)	yes
sandbox	string	yes
started_at	string (date-time)	yes
state	string	yes	One of running, exited.
truncated	boolean	yes

ExecRequest

Field	Type	Required	Description
attach	boolean	no
command	array of string	yes	At least 1 item.
env	array of string	no
size	TerminalSize	no
stdin	boolean	no
tty	boolean	no
user	string	no
workdir	string	no

ExecsResponse

Field	Type	Required
execs	array of Exec	yes
next	string or null	yes

ExitMessage

Field	Type	Required	Description
code	integer (int64)	yes	The exit code, or the code a command that never started ends with.
error	string	no	Why the command never started; absent when it started.
lost_bytes	integer (int64)	no	The output bytes the buffer dropped before this client read them; absent when it dropped none.
signal	integer (int64)	yes	The signal that ended the command, or 0.

FailureError

Field	Type	Required	Description
code	string	yes	One of the codes of ErrorObject.code.
message	string	yes

FailureMessage

Field	Type	Required
error	FailureError	yes

KillRequest

Field	Type	Required	Description
signal	string	no	TERM or KILL, in capitals; absent or empty is TERM.

TerminalSize

Field	Type	Required	Description
cols	integer (int32)	no	From 0 to 65535.
rows	integer (int32)	no	From 0 to 65535.