Files

This copies a file and a directory into the running sandbox web, then lists the directory that holds them:

curl --unix-socket /var/lib/shard/shard.sock -T ./app.conf 'http://localhost/v0/sandboxes/web/files?path=/srv/app.conf&mode=600'
tar -cf - app | curl --unix-socket /var/lib/shard/shard.sock -T - 'http://localhost/v0/sandboxes/web/archive?path=/srv'
curl --unix-socket /var/lib/shard/shard.sock 'http://localhost/v0/sandboxes/web/ls?path=/srv'

To copy out, send a GET to the same route:

curl --unix-socket /var/lib/shard/shard.sock -o app.conf 'http://localhost/v0/sandboxes/web/files?path=/srv/app.conf'
curl --unix-socket /var/lib/shard/shard.sock 'http://localhost/v0/sandboxes/web/archive?path=/srv/app' | tar -xf -

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

Copy a file into a running sandbox

PUT /v0/sandboxes/{id}/files · scope exec

Parameters

Name	In	Type	Required	Description
id	path	string	yes	The sandbox id or name.
path	query	string	yes	The absolute path inside the sandbox.
mode	query	string	no	The permission bits in octal, at most 0777; absent is 0644.
user	query	string	no	The user who writes and owns the file; absent is the sandbox’s user.
parents	query	boolean	no	Make the missing parent directories.

Request body

binary as application/octet-stream, required.

Responses

Status	Body	Description
204	none	The file is written. The upload sets Content-Length to its number of bytes.

Copy a file out of a running sandbox

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

Parameters

Name	In	Type	Required	Description
id	path	string	yes	The sandbox id or name.
path	query	string	yes	The absolute path inside the sandbox.

Responses

Status	Body	Description
200	binary as application/octet-stream	The file’s bytes, chunked to the end; a body cut short is a failed read.

Response headers

Header	Status	Type	Description
X-Shard-Stat	200	string	The stat of the path as JSON: type is file, dir, symlink or other; size is the logical size in bytes; mode is the permission bits as a number, at most 0o7777; then uid, gid and mtime.

Read the type, size and mode of a path

HEAD /v0/sandboxes/{id}/files · scope exec

Parameters

Name	In	Type	Required	Description
id	path	string	yes	The sandbox id or name.
path	query	string	yes	The absolute path inside the sandbox.

Responses

Status	Body	Description
200	none	The path’s stat, in a header and no body.
Error	none	Error, as the status alone: a HEAD answer has no body.

Response headers

Header	Status	Type	Description
X-Shard-Stat	200	string	The stat of the path as JSON: type is file, dir, symlink or other; size is the logical size in bytes; mode is the permission bits as a number, at most 0o7777; then uid, gid and mtime.

Delete a path

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

Parameters

Name	In	Type	Required	Description
id	path	string	yes	The sandbox id or name.
path	query	string	yes	The absolute path inside the sandbox.
recursive	query	boolean	no	Delete a directory and everything in it.

Responses

Status	Body
204	none

List a directory

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

Parameters

Name	In	Type	Required	Description
id	path	string	yes	The sandbox id or name.
path	query	string	yes	The absolute path inside the sandbox.

Responses

Status	Body	Description
200	EntriesResponse as application/json	The directory’s entries; a listing cut short never parses.

Make a directory

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

Parameters

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

Request body

MkdirRequest as application/json, required.

Responses

Status	Body
204	none

Copy a directory into a running sandbox

PUT /v0/sandboxes/{id}/archive · scope exec

Parameters

Name	In	Type	Required	Description
id	path	string	yes	The sandbox id or name.
path	query	string	yes	The absolute directory inside the sandbox.
user	query	string	no	The user who unpacks and owns the files; absent is the sandbox’s user.

Request body

binary as application/x-tar, required.

Responses

Status	Body	Description
204	none	The tar unpacked under the directory.

Copy a directory out of a running sandbox

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

Parameters

Name	In	Type	Required	Description
id	path	string	yes	The sandbox id or name.
path	query	string	yes	The absolute path inside the sandbox.

Responses

Status	Body	Description
200	binary as application/x-tar	A tar of the path; a body cut short is a failed read.

Response headers

Header	Status	Type	Description
X-Shard-Stat	200	string	The stat of the path as JSON: type is file, dir, symlink or other; size is the logical size in bytes; mode is the permission bits as a number, at most 0o7777; then uid, gid and mtime.

Objects

EntriesResponse

Field	Type	Required
entries	array of FileEntry	yes

FileEntry

Field	Type	Required	Description
gid	integer (int32)	yes	At least 0.
mode	integer (int32)	yes	The permission bits with setuid, setgid and sticky as a number, at most 0o7777 (4095); the type is in type. At least 0.
mtime	string (date-time)	yes
name	string	yes
size	integer (int64)	yes	The logical size in bytes.
type	string	yes	One of file, dir, symlink, other.
uid	integer (int32)	yes	At least 0.

MkdirRequest

Field	Type	Required	Description
mode	string	no	The permission bits in octal, at most 0777; absent is 0755.
parents	boolean	no
path	string	yes	At least 1 character.
user	string	no