sandctl
sandctl is the Sandswap client CLI: the gateway HTTPS API client, DNS querying, and read-only pool/health views. It never starts, stops or configures a component — installation and lifecycle belong to the bare-metal deployers (systemctl, journalctl, sandswap-ops.sh).
bash build/build.sh sandctl # → output/sandctl
It is a standalone stdlib-only Go module. It talks to an already-deployed stack and needs no root: the deployers publish a client contract, and the API commands run as the invoking user.
1. Usage
sandctl [global-flags] <command> [subcommand] [flags] [args]
| Command | Description |
|---|---|
api <sub> | gateway HTTPS API client (§4) |
dns <sub> | DNS queries (§5) |
pool | cluster pool view (§3) |
health-all | probe /health + /ready (§3) |
version | print version, commit, and build time (ldflags-stamped by build/build.sh; dev builds show the defaults) |
1.1 Global flags
| Flag | Default | Description |
|---|---|---|
--run-dir DIR | ./run | agent-key cache root (agents.json only) |
--bin-dir DIR | ./output | component binary dir, for the vendored etcdctl |
--gateway-url URL | http://127.0.0.1:3000 | agent listener base URL |
--human-url URL | http://127.0.0.1:3100 | human listener base URL |
--dns-addr ADDR | 127.0.0.1:8053 | DNS server address |
--etcd URL | http://127.0.0.1:2379 | etcd client endpoint |
--tls | off | enable TLS for the HTTPS listeners / etcd |
--ca FILE | — | CA bundle (absolute, or relative to <run-dir>/certs) |
--client-cert FILE | — | mTLS client certificate (caller-owned) |
--client-key FILE | — | mTLS client key (caller-owned, mode 0600) |
--insecure | off | skip TLS verification (development only) |
--raw | off | don’t pretty-print JSON |
--dry-run | off | print the HTTP request, don’t send |
2. Client contract discovery
The deployers write /etc/sandswap/sandctl.env once the deployment is healthy. sandctl reads it automatically; CLI flags always win.
Resolution order:
- CLI flags (explicit values are never overridden)
$SANDSWAP_SANDCTL_ENV— an explicit contract file; if set it must exist and be readable (a missing override is an error, never a silent fallback)/etc/sandswap/sandctl.env— the deployer-written contract; absent means the built-in defaults apply
Contract format (key=value, # comments):
# Generated by the Sandswap deployer — sandctl client contract.
# Public endpoints and the CA trust anchor only. No private keys.
gateway_url=https://127.0.0.1:3000
human_url=https://127.0.0.1:3100
tls=true
ca=/etc/sandswap/certs/ca.crt
etcd=https://127.0.0.1:2379 # distributed shapes only
The file is root:root 0644 and carries public material only — URLs and the CA trust anchor. It never names a private key.
The client contract is the only configuration source; --run-dir holds the local agent-key cache only.
2.1 Credential isolation
The deployers scope every service private key to the identity that loads it (CA certificates are public 0644; service keys are 0640/0600 and owned by sandserv/sandlot). The client follows the same boundary:
sandctlnever auto-loads/etc/sandswap/certs/*.key. The HTTP listeners authenticate the server only, so a client needs just the CA.--client-cert/--client-keyare for mTLS deployments and must be caller-owned: the key must be a regular file, mode0600(no group/world bits), owned by the invoking user (or root). A service identity’s key is refused by name.run/agents.json(the API-key cache) is0600and owned by the invoking user; a cache that group/world can read is refused with a warning.- etcd-backed queries use ONLY explicit
--ca/--client-cert/--client-key.poolnormally needs no credentials: it falls back to the human listener’s anonymous/stats.
3. Pool and health views
| Command | Description | Flags |
|---|---|---|
pool | cluster pool view. etcd-first: reads /sandswap/{load,health,gateway}/ directly (multi-gateway). Falls back to GET /stats in single-node MemoryStore mode. Both return the same StatsReport shape. | --raw |
health-all | probe gateway + human /health + /ready; exit 1 when any probe fails (transport error or HTTP ≥ 400). | — |
The deploy’s etcd client key belongs to the sandserv identity; pool therefore uses /stats for an ordinary user. Root (or a caller with an explicitly supplied etcd client key) can use the etcd path.
4. The gateway API client (api)
Agent api-key resolution, in order: --api-key <key> (accepted but deprecated — it warns, because the value is visible to every local user via /proc/<pid>/cmdline); else the SANDSWAP_API_KEY environment variable; else SANDSWAP_API_KEY_FILE (a file whose contents are the key — point it at an 0600 credential file); else --agent <id> looks up run/agents.json (populated by api agent create). Prefer the environment variable or the file form in scripts and units.
4.1 Misc
| Subcommand | Endpoint |
|---|---|
api health | GET /health (tries agent then human listener) |
api ready | GET /ready |
api stats | GET /stats (human listener) |
4.2 Agents (/human/agent)
create, list, and delete accept -ns <ns> / --namespace <ns>: with it the call maps onto the namespaced tenant surface (/human/ns/<ns>/…); without it the fleet-wide admin surface is used (which requires the * namespace grant when OIDC is configured — see Namespaces).
| Subcommand | Flags |
|---|---|
api agent create | --name (required) |
api agent list | --limit (page size; 0 = server default 100, max 1000), --all (follow cursors and print every page) |
api agent delete <agent_id> | — |
4.3 SandFS (/human/sandfs)
The same -ns/--namespace flag applies to every api sandfs subcommand.
| Subcommand | Flags |
|---|---|
api sandfs create | --agent (required), --name (required), --template (required), --mode (default flat), --vcpus, --memory-mb, --description |
api sandfs list | --limit, --all (as agent list) |
api sandfs get <sandfs_id> | — |
api sandfs delete <sandfs_id> | — |
api sandfs save-template <sandfs_id> | --name, --version, --vcpus, --memory-mb (override; 0 = inherit source sandfs) |
api sandfs detach-template <sandfs_id> | --wait-sec (drain wait budget; 0 = server default 15) |
api sandfs attach-template <sandfs_id> <template_ref> | --home keep\|archive\|reset (default keep) |
api sandfs swap-template <sandfs_id> <template_ref> | --home keep\|archive\|reset, --wait-sec |
The four template subcommands are the detach/attach/swap lifecycle — see SandFS §Template swap.
4.4 Templates (/human/templates)
| Subcommand | Flags | Description |
|---|---|---|
api template list | — | list locally stored templates |
api template pull <ref> | --mode=flat\|overlay | pull a template from the OCI registry |
api template push <ref> | --mode=flat\|overlay | push a local template to the OCI registry |
api template delete <ref> | --mode=flat\|overlay, --force | delete a local template (the two-layer in-use check refuses with 409 TEMPLATE_IN_USE unless forced) |
4.5 Ownership (/human/ownership)
| Subcommand | Description |
|---|---|
api ownership release <sandfs_id> | release ownership so another gateway can claim it |
api ownership reap-stuck <gw-id> | reclaim a dead owner’s sandfs (--dry-run, --batch=N) |
api ownership reap-stuck-node <node-id> | reclaim all sandfs placed on a dead node (--dry-run, --batch=N) |
4.6 Execution (/agent/execute)
| Subcommand | Flags |
|---|---|
api execute | --agent / --api-key, --sandfs (required), --code (required), --language (default shell), --timeout (sync, seconds), --background, --lease (background run-time cap, seconds) |
api exec-status <exec_id> | --agent / --api-key, --sandfs (required) |
api exec-kill <exec_id> | --agent / --api-key, --sandfs (required) |
4.7 File operations (/agent/file)
| Subcommand | Flags |
|---|---|
api file | --agent / --api-key, --sandfs (required), --action (required), --path (required), plus action-specific flags below |
--action values and their flags:
| Action | Extra flags |
|---|---|
read | --offset, --length |
write | --data (text) or --data-base64 (binary), --offset, --append, --mode |
stat | — |
list_dir | --depth (default 1) |
mkdir | --mode |
remove | --recursive |
rename | --new-path (required) |
5. DNS queries
| Subcommand | Description |
|---|---|
dns stream | resolve the stream domain (sandswap-stream.local, short form) |
dns agent | resolve the agent discovery domain (sandswap.local, short form) |
dns sandfs <id> | resolve <id>.sandfs.sandswap.local (full output — owner-aware CNAME/A chain) |
dns resolve <name> | query an arbitrary name (full output) |
dns sticky | list sticky records from etcd (/sandswap/dns/sticky/) via etcdctl |
The query subcommands use a built-in Go resolver pointed at --dns-addr (default 127.0.0.1:8053), so no dig is required (dig remains an optional manual debugging tool). dns sticky reads etcd through etcdctl; on a release package that resolves to the bundled output/etcd/etcdctl, and on a source build to the copy on PATH. It needs explicit etcd client credentials (the deploy’s etcd key is the sandserv identity’s, not a client credential) and therefore normally runs as root on the deployed host.