Host and access

shard capabilities

Show sandbox lifecycle capabilities supported by the connected shard server.

shard capabilities [OPTIONS]

Examples

shard capabilities
shard capabilities --format json

Options

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

Lists all nine verbs and swap, each true or false for the server’s provider. Token scopes and sandbox states never change the answer.

shard daemon

Start the daemon or show its status.

shard daemon [OPTIONS]
shard daemon status [OPTIONS]

Examples

shard daemon
shard daemon --provider gvisor

Commands

Command	Description
shard daemon status	show daemon status

Options

Option	Description	Default
--provider <name>	sandbox provider: gvisor, sysbox, runc, vz or firecracker
--timeout <duration>	image download timeout	30m
--insecure-registry <host>	allow HTTP for a registry; repeatable
--log <path>	daemon log file (macOS only)
--storage-size <size>	size of a new Firecracker data image

The daemon manages local sandboxes and stays active until stopped. An existing data directory must use its original provider. Use shard info to see the default provider for this host. A new Firecracker data image takes half the free space, at most 100GiB, unless --storage-size sets it. An existing one keeps its size, and the daemon refuses any other --storage-size.

Runs only on the daemon host and refuses --remote, SHARD_REMOTE and a saved connection.

shard daemon status

Show daemon status.

shard daemon status [OPTIONS]

Examples

shard daemon status
shard daemon status --format json

Options

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

Shows the version, provider, process details and background tasks.

Runs only on the daemon host and refuses --remote, SHARD_REMOTE and a saved connection.

shard info

Show available providers and the default for this host.

shard info [OPTIONS]

Examples

shard info
shard info --format json

Options

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

Works without an active daemon. Use shard daemon status to see the provider the current daemon uses.

Runs only on the daemon host and refuses --remote, SHARD_REMOTE and a saved connection.

shard serve

Start an HTTP API server with token authentication.

shard serve [OPTIONS]

Example

shard serve

Options

Option	Description	Default
--listen <address>	listen address	127.0.0.1:7850
--signing-key-file <path>	token signing key	<root>/auth/signing-key

The local daemon must be active. Use shard tokens mint to create API keys.

Use an HTTPS proxy or tunnel for public access. HTTP is suitable for local access or an encrypted VPN.

The default signing key is created automatically on first use. A custom signing key file must already exist.

Runs only on the daemon host and refuses --remote, SHARD_REMOTE and a saved connection.

shard setup

Set up shard on this machine or connect to a remote server.

Run without options to start the interactive wizard. For automated setup, specify the choices below.

shard setup [OPTIONS]

Examples

shard setup
shard setup --local --provider gvisor --start-at-boot=true -y
shard setup --local --provider firecracker --start-at-boot=true --storage-size 50GiB -y
shard setup --local --provider gvisor --http-api=true --listen 100.64.0.5:7850 -y
shard setup --remote https://shard.example.com --save -y

Options

Option	Description	Default
--local	set up this machine to run sandboxes
--remote <url>	connect to a remote shard server
--provider <name>	firecracker, gvisor, sysbox, runc or vz
--start-at-boot <true|false>	start the daemon at boot
--storage-size <size>	space to reserve for Firecracker sandbox disks
--http-api <true|false>	set up the HTTP API as a background service	false
--listen <address>	address of the HTTP API	127.0.0.1:7850
--replace-api-key	replace the existing API key of the HTTP API
--save	save the remote connection
-y, --yes	apply changes without confirmation

Remote authentication

Set SHARD_API_KEY. Do not pass the key as a command argument.

Storage size

Without XFS or Btrfs, Firecracker keeps sandbox disks in one XFS image. The daemon reserves it whole when it starts, and keeps 10GiB for the host. The default is half the available space, at most 100GiB. The minimum is 10GiB. Sizes take KiB, MiB, GiB, KB, MB or GB, as --disk does. Setup does not resize an existing image. Other providers refuse the option.

HTTP API

The HTTP API serves plain HTTP. Setup does not configure HTTPS. 127.0.0.1:7850 accepts connections only from this machine. Reach it through an SSH tunnel or an HTTPS proxy. A VPN address permits direct access through that private network. Setup saves the API key in a protected file and shows the file, not the key. A repeated setup keeps the key. Pass --replace-api-key to replace it. On an existing installation, --http-api true sets up or changes the HTTP API. API requests fail when the daemon is stopped.

Exit codes

• 0: setup finished, or there was nothing to do
• 1: a check or a step failed, an option was refused, the confirmation was declined, or setup found a manual installation
• 130: Ctrl+C left setup; the steps done so far stay in place

shard tokens

Create, list and revoke API keys.

shard tokens COMMAND [OPTIONS] [ARGS...]

Commands

Command	Description
shard tokens mint	create an API key
shard tokens list	list API keys and their status
shard tokens revoke	revoke an API key
shard tokens scopes	list available token scopes

mint, list and revoke run only on the daemon host and refuse --remote. scopes follows --remote and SHARD_REMOTE.

shard tokens mint

Create an API key.

shard tokens mint [OPTIONS]

Examples

shard tokens mint --name build-agent --duration 24h
shard tokens mint --name reader --duration 24h --scopes sandbox:read

Options

Option	Description	Default
--name <name>	token owner or purpose; required
--duration <duration>	token lifetime; default no expiry
--scopes <list>	permissions, separated by commas; default all permissions
--signing-key-file <path>	token signing key	<root>/auth/signing-key
--format <format>	output format: json or table	json

Use shard tokens scopes to list available scopes.

The default signing key is created automatically on first use. A custom signing key file must already exist.

The response includes the API key. Use its token value as SHARD_API_KEY.

Runs only on the daemon host and refuses --remote, SHARD_REMOTE and a saved connection.

shard tokens list

List API keys and their status.

shard tokens list [OPTIONS]

Examples

shard tokens list
shard tokens list --format json

Options

Option	Description	Default
--signing-key-file <path>	locate the token registry beside this key	<root>/auth/signing-key
--format <format>	output format: json or table	table

Table columns: ID, NAME, ISSUED, EXPIRES, SCOPES and STATUS. Does not create a signing key.

Runs only on the daemon host and refuses --remote, SHARD_REMOTE and a saved connection.

shard tokens revoke

Revoke an API key.

shard tokens revoke [OPTIONS] TOKEN
shard tokens revoke [OPTIONS] --name NAME

Examples

shard tokens revoke 0123456789abcdef
shard tokens revoke --name build-agent

Arguments

Argument	Description
TOKEN	token ID from shard tokens list

Options

Option	Description	Default
--name <name>	revoke all tokens with this name
--signing-key-file <path>	locate the token registry beside this key	<root>/auth/signing-key

Revoked tokens are rejected on subsequent requests.

Runs only on the daemon host and refuses --remote, SHARD_REMOTE and a saved connection.

shard tokens scopes

List available token scopes.

shard tokens scopes [OPTIONS]

Examples

shard tokens scopes
shard tokens scopes --format json

Options

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

shard version

Show the client and daemon versions.

shard version [OPTIONS]

Examples

shard version
shard version --format json

Options

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

Use shard --version to show only the client version.