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:

  1. CLI flags (explicit values are never overridden)
  2. $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)
  3. /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:

  • sandctl never auto-loads /etc/sandswap/certs/*.key. The HTTP listeners authenticate the server only, so a client needs just the CA.
  • --client-cert / --client-key are for mTLS deployments and must be caller-owned: the key must be a regular file, mode 0600 (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) is 0600 and 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. pool normally 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.