Sandboxes

shard create

Create a sandbox and print its ID.

shard create [OPTIONS] IMAGE
shard create [OPTIONS] --snapshot SNAPSHOT

Examples

shard create --name web --memory 512MiB python:3.12
shard create --name web-copy --snapshot web-files
shard create --name worker --memory 512MiB --secret API_TOKEN python:3.12
shard create --name web --port 8000 python:3.12

Arguments

Argument	Description
`IMAGE`	image to use; downloaded if needed

Options

Option	Description
`--name <name>`	sandbox name to use instead of its ID
`--env KEY=VALUE`	set an environment variable; repeatable
`--secret <NAME>`	let the sandbox use a stored secret; repeatable
`--policy <name>`	outbound network policy
`--workdir <dir>`	default directory for commands
`--user <user>`	default user for commands
`--memory <size>`	memory limit; 512MiB by default on Firecracker and vz, none on gVisor, runc and Sysbox
`--vcpus <n>`	CPU count; 0 uses all available host CPUs, up to 32 on Firecracker
`--disk <size>`	disk limit; 0 uses the default
`--swap <size>`	swap file inside the disk limit; 2GiB by default on Firecracker and vz, 0 for none
`--snapshot <id\|name>`	create from a filesystem snapshot instead of an image
`--port [HOST:]GUEST`	forward a port on the host’s 127.0.0.1 to the sandbox; repeatable

The sandbox starts with no processes. Use shard run to start a supervised process in it, or shard exec for a one-off command. The sandbox stays active until stopped.

Names

Use lower-case letters, digits, hyphens and underscores.

Secrets

Store a secret with shard secret set, then select it with --secret. Commands receive $NAME with a placeholder instead of the secret value. In HTTPS request headers sent to approved destinations, shard replaces the placeholder with the secret. The secret value stays outside the sandbox.

Network access

Without a policy, the sandbox can access the internet but not private networks. Use shard policy attach to assign a policy after creation.

Resource limits

Use sizes such as 512MiB or 2GiB, and whole numbers for CPUs. gVisor, runc and Sysbox refuse any --swap but 0.

shard run

Start a supervised process in a running sandbox.

shard run SANDBOX [OPTIONS] [--] COMMAND [ARGS...]

Examples

shard run web --name api -- python -m http.server
shard run web --name db --restart on-failure --restart-retries 5 -- pg_ctlcluster 16 main start --foreground
shard run web --restart no --attach -- python script.py

Arguments

Argument	Description
`SANDBOX`	sandbox ID or name
`COMMAND`	command to execute
`ARGS`	arguments for the command

Options

Option	Description	Default
`--name <name>`	process name; COMMAND’s base name by default
`-e, --env KEY=VALUE`	set an environment variable; repeatable
`-w, --workdir <dir>`	directory for this process
`-u, --user <user>`	user for this process
`--restart <policy>`	restart policy	`unless-stopped`
`--restart-retries <n>`	restart limit for on-failure; default unlimited
`--restart-backoff <duration>`	initial restart delay, up to 1m	`1s`
`--attach`	stay for the output and exit with its code

Prints the process name and returns; the process runs on in the background. A sandbox runs up to 16 processes, each under its own name. A run of an ended name replaces it, and its log keeps the earlier output.

With --attach, Ctrl+C detaches and leaves the process running. It exits with the process’s last exit code, or 128 plus the ending signal. An exit code of 125 means shard itself failed.

Restarts

no: do not restart the process
on-failure: restart after a nonzero exit
always: restart after any exit, and whenever the sandbox starts
unless-stopped: like always, until shard kill ends it (default)

--restart-retries applies to on-failure only. Restart delays double after each restart, up to 60s. When the daemon starts, it starts the sandboxes these policies bring back, except unless-stopped ones in a sandbox that shard stop stopped.

Names

Use up to 32 lower-case letters, digits, dots, hyphens and underscores.

shard exec

Execute a command in a running sandbox.

shard exec [OPTIONS] SANDBOX COMMAND [ARGS...]

Examples

shard exec web python script.py
shard exec --workdir /app web npm test
shard exec -it web python

Arguments

Argument	Description
`SANDBOX`	sandbox ID or name
`COMMAND`	command to execute
`ARGS`	arguments for the command

Options

Option	Description
`-i, --interactive`	keep standard input open
`-t, --tty`	use a terminal; requires `--interactive`
`--env KEY=VALUE`	set an environment variable for this command; repeatable
`--workdir <dir>`	directory for this command
`--user <user>`	user for this command

The command uses the sandbox’s default directory and user unless overridden. The exit code is the command’s exit code. To open a shell in the sandbox, use shard shell.

shard shell

Open an interactive shell in a running sandbox.

shard shell [OPTIONS] SANDBOX

Examples

shard shell web
shard shell --workdir /app web
shard shell --user root web

Arguments

Argument	Description
`SANDBOX`	sandbox ID or name

Options

Option	Description
`--workdir <dir>`	directory for the shell
`--user <user>`	user for the shell

The shell is bash if the sandbox has it, and sh if not. It keeps the PATH the image sets. It uses the sandbox’s default directory and user unless overridden. Standard input must be a terminal. To run a command without one, use shard exec. The exit code is the shell’s exit code.

shard list

List active sandboxes.

shard list [OPTIONS]

Examples

shard list
shard list --all
shard list --format json
shard list -q

Options

Option	Description	Default
`--all`	include stopped sandboxes
`-q, --quiet`	print only sandbox IDs, one per line
`--format <format>`	output format: json or table	`table`

Table columns: ID, NAME, IMAGE, STATE, UPTIME, PROCESSES and POLICY. PROCESSES counts the running processes of all the sandbox has.

Use --quiet to pass the IDs to another command, as in shard stop $(shard list -q). --quiet cannot be combined with --format.

shard ps

List the processes of a sandbox.

shard ps [OPTIONS] SANDBOX

Examples

shard ps web
shard ps --format json web

Arguments

Argument	Description
`SANDBOX`	sandbox ID or name

Options

Option	Description	Default
`--format <format>`	output format: json or table	`table`

Table columns: NAME, STATE, RESTARTS, EXIT, POLICY and COMMAND. A state is running, restarting, exited, killed, gave-up or stopped.

shard logs

Show output from a process.

shard logs SANDBOX [NAME] [OPTIONS]

Examples

shard logs web
shard logs web api -f

Arguments

Argument	Description
`SANDBOX`	sandbox ID or name
`NAME`	process name

Options

Option	Description
`-f, --follow`	show new output until the process ends or the sandbox stops

Without a NAME, shows the sandbox’s only process; with several, name one. The output of every run of the process is kept, restarts included.

shard kill

Stop a process and cancel its restarts.

shard kill SANDBOX NAME [OPTIONS]

Examples

shard kill web api
shard kill web api --force

Arguments

Argument	Description
`SANDBOX`	sandbox ID or name
`NAME`	process name

Options

Option	Description
`--force`	kill at once instead of asking the process to exit

The process has up to 30 seconds to exit before it is terminated. The sandbox stays running, and only an always policy brings the process back. Use shard run with the same name to start it again.

shard inspect

Show detailed information about a sandbox.

shard inspect [OPTIONS] SANDBOX

Examples

shard inspect web
shard inspect --format table web

Arguments

Argument	Description
`SANDBOX`	sandbox ID or name

Options

Option	Description	Default
`--format <format>`	output format: json or table	`json`

shard stop

Stop sandboxes and preserve their files.

shard stop SANDBOX [SANDBOX...]

Examples

shard stop web
shard stop web worker
shard stop $(shard list -q)

Arguments

Argument	Description
`SANDBOX`	sandbox ID or name; repeatable

Each process has up to 30 seconds to exit before it is terminated. Files remain available, but memory and process state are lost.

Use shard start to start the sandbox again. Use shard snapshot create to save its files as a snapshot.

With more than one sandbox, each ID prints as soon as that sandbox succeeds. If a sandbox fails, the command goes on to the next one. The failures print at the end, and the exit code is 1.

shard start

Start a stopped sandbox with its saved files.

shard start SANDBOX

Example

shard start web

Arguments

Argument	Description
`SANDBOX`	sandbox ID or name

Processes with the always or unless-stopped policy start again, except those killed.

shard remove

Remove sandboxes and their files.

shard remove [OPTIONS] SANDBOX [SANDBOX...]

Examples

shard remove web
shard remove --force web
shard remove --force web worker

Arguments

Argument	Description
`SANDBOX`	sandbox ID or name; repeatable

Options

Option	Description
`--force`	stop each sandbox first if needed; ignore a missing sandbox

Stop a running or paused sandbox before removal, or use --force. A sandbox with an image download in progress can be removed directly.

With more than one sandbox, each ID prints as soon as that sandbox succeeds. If a sandbox fails, the command goes on to the next one. The failures print at the end, and the exit code is 1.

shard prune

Remove every stopped sandbox and its files, and print the ID of each one removed.

shard prune [OPTIONS]

Examples

shard prune
shard prune --force

Options

Option	Description
`--force`	remove without asking for confirmation

Running and paused sandboxes are never removed. Before it removes anything, prune lists the stopped sandboxes and asks for confirmation. Without a terminal, it refuses unless --force is given.

shard pause

Suspend sandboxes and save their state.

shard pause SANDBOX [SANDBOX...]

Examples

shard pause web
shard pause web worker

Arguments

Argument	Description
`SANDBOX`	sandbox ID or name; repeatable

Memory and files are saved so its processes can continue after resume. The sandbox must be running. Availability depends on the provider.

With more than one sandbox, each ID prints as soon as that sandbox succeeds. If a sandbox fails, the command goes on to the next one. The failures print at the end, and the exit code is 1.

shard resume

Resume paused sandboxes from their saved state.

shard resume SANDBOX [SANDBOX...]

Examples

shard resume web
shard resume web worker

Arguments

Argument	Description
`SANDBOX`	sandbox ID or name; repeatable

Processes continue from where they paused.

With more than one sandbox, each ID prints as soon as that sandbox succeeds. If a sandbox fails, the command goes on to the next one. The failures print at the end, and the exit code is 1.

shard fork

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

shard fork [OPTIONS] SANDBOX

Example

shard fork --name web-copy web

Arguments

Argument	Description
`SANDBOX`	source sandbox ID or name

Options

Option	Description
`--name <name>`	name for the new sandbox

The source briefly pauses, then continues running. The new sandbox starts from the captured state and has independent files. Prints the new sandbox ID. Availability depends on the provider.

shard cp

Copy files or directories between your machine and a running sandbox.

shard cp [OPTIONS] SOURCE SANDBOX:PATH
shard cp SANDBOX:PATH DESTINATION

Examples

shard cp ./app web:/srv/
shard cp web:/tmp/results.json ./results.json

Arguments

Argument	Description
`SOURCE, DESTINATION`	path on your machine
`SANDBOX:PATH`	sandbox ID or name, followed by a path

Options

Option	Description
`--user <user>`	user for copies into the sandbox; defaults to its user

When the destination is a directory, the source is copied inside it. Prefix local paths that contain a colon with ./ or /. Successful copies produce no output.

shard port

Forward host ports to ports inside sandboxes.

shard port COMMAND [OPTIONS] [ARGS...]

Commands

Command	Description
`shard port add`	forward a host port to a port inside a sandbox
`shard port list`	list forwarded host ports
`shard port remove`	stop forwarding a host port

A forward carries TCP from a host port to a port on the sandbox’s 127.0.0.1. It belongs to the sandbox, and listens whenever the sandbox runs.

shard port add

Forward a host port to a port inside a sandbox, or change the forward it has.

shard port add [OPTIONS] SANDBOX [HOST:]GUEST

Examples

shard port add web 8000
shard port add web 9000:8000
shard port add web 9000:8000 --public

Arguments

Argument	Description
`SANDBOX`	sandbox ID or name
`HOST`	port on the host; the guest port when omitted
`GUEST`	port the program in the sandbox listens on, on 127.0.0.1

Options

Option	Description
`--public`	listen on 0.0.0.0, every interface of the host, not 127.0.0.1

Prints each address of the host the port is reachable on. A running sandbox takes the forward at once; any other from its next start. The forward survives a stop, a start and a host reboot. A fork does not copy it.

Add the same host port again to change its guest port or its visibility. --public is the only way to listen beyond this host; it opens the port to every network the host is on.

shard port list

List the host ports forwarded into one sandbox, or into every sandbox.

shard port list [OPTIONS] [SANDBOX]

Examples

shard port list
shard port list web
shard port list --format json

Arguments

Argument	Description
`SANDBOX`	sandbox ID or name; every sandbox when omitted

Options

Option	Description	Default
`--format <format>`	output format: json or table	`table`

Table columns: SANDBOX, HOST, GUEST, VISIBILITY and REACHABLE-ON. REACHABLE-ON shows a dash while the sandbox is not running.

shard port remove

Stop forwarding a host port.

shard port remove SANDBOX HOST

Example

shard port remove web 9000

Arguments

Argument	Description
`SANDBOX`	sandbox ID or name
`HOST`	host port the forward listens on

Closes the listener and the connections it carries.