Quickstart: client

Use this page when the sandboxes run on another machine and you drive them from yours. To run sandboxes on this machine, see Quickstart: server.

Connect to a shard server and run a command in a new sandbox:

CLI

curl -fsSL https://useshards.com/install | sh
export SHARD_API_KEY='your-api-key'
shard setup --remote https://shard.example.com --save -y

shard create --name demo --memory 512MiB alpine:3.20
shard exec demo echo hello
shard remove --force demo

To open a shell in the sandbox, run shard shell demo before you remove it.

TypeScript

npm install useshards
export SHARD_REMOTE=https://shard.example.com
export SHARD_API_KEY='your-api-key'

import { Shard } from "useshards";

const shard = new Shard();
const sandbox = await shard.create({ image: "docker.io/library/alpine:3", memoryMiB: 512 });
try {
  const result = await sandbox.exec(["uname", "-sr"]);
  console.log(result.exitCode, result.stdout);
} finally {
  await sandbox.remove({ force: true });
  shard.close();
}

Python

pip install useshards
export SHARD_REMOTE=https://shard.example.com
export SHARD_API_KEY='your-api-key'

from useshards import Shard

with Shard() as shard:
    sandbox = shard.create("docker.io/library/alpine:3", memory_mib=512)
    try:
        result = sandbox.exec(["uname", "-sr"])
        print(result.exit_code, result.stdout)
    finally:
        sandbox.remove(force=True)

Replace https://shard.example.com with the URL of your server and your-api-key with an API key from that server. The TypeScript SDK needs Node 20.3 or later, and the Python SDK needs Python 3.11 or later.

What you need

You need a server that runs shard serve. The daemon itself never serves its API on the network. shard serve is a separate process that checks an API key and passes each request to the daemon, usually behind an HTTPS proxy. See How to connect to a remote host?.

You also need an API key from that server. Mint one on the server, with sudo on Linux:

shard tokens mint --name build-agent --duration 24h

The command prints a JSON record. Its token value is the API key. Without --scopes, the key can do everything. Without --duration, it never expires. shard tokens scopes lists the scopes you can pass.

Connect the CLI

Run shard setup with no options, and choose Connect to a remote server. The wizard asks for the server URL and the API key. If SHARD_API_KEY is set, the wizard uses it. Otherwise it asks for the key and hides what you type.

Setup then checks three things: that it can reach the server, that the server accepts the key, and which lifecycle verbs the server supports. If a check fails, you can retry, edit the details or exit.

When the checks pass, setup offers to save the connection. Later client commands then use it without a flag or a variable. The file is ~/.config/shard/config.json, or $XDG_CONFIG_HOME/shard/config.json when that variable contains an absolute path. It holds the key in plain text, so setup makes it readable only by your user.

If you do not save the connection, set both variables in each shell:

export SHARD_REMOTE=https://shard.example.com
export SHARD_API_KEY='your-api-key'

A command picks its server and key in this order:

Setting	First	Then	Last
Server URL	--remote	SHARD_REMOTE	the saved connection
API key	SHARD_API_KEY		the saved connection

The CLI sends the saved key only to the server you saved it for. --remote "" runs a command against the daemon on this machine instead.

Commands that run on the server only

A few commands act on the daemon’s own host, so they refuse a remote: pull, image list, image remove, image prune, info, daemon status, tokens mint, tokens list and tokens revoke. Run them on the server. On a machine with a saved connection, add --remote "" to use this host instead.

You do not need to pull before shard create. The server fetches a missing image itself.

Connect an SDK

The SDKs ignore the connection that shard setup saves. They read SHARD_REMOTE and SHARD_API_KEY, and an option you pass wins over its variable:

TypeScript

const shard = new Shard({ remote: "https://shard.example.com", apiKey: process.env.MY_SHARD_KEY });

Python

import os

from useshards import Shard

shard = Shard(remote="https://shard.example.com", api_key=os.environ["MY_SHARD_KEY"])

HTTPS and certificates

Use an https URL. An http URL works, but it sends the API key and every request unencrypted. Setup asks you to confirm an http URL. The CLI and both SDKs warn when they connect over HTTP. Use http only on localhost or through a trusted encrypted network.

For HTTPS, the CLI and both SDKs always verify the server’s certificate, and no option turns that off. If a private certificate authority signed it, set SHARD_CA_FILE to that authority’s PEM file. The saved connection does not store this path, so keep the variable set. The TypeScript SDK also takes caFile, and the Python SDK takes ca_file=.

Next steps

• The TypeScript README and the Python README cover background commands, files and errors.
• To check, replace or remove the saved connection, run shard setup again. Its first screen names the saved server.