CLI

Run better-compute help <command> for the same text in a terminal, or better-compute help --json for this manifest.

Setup

init

Write a starter configuration file

better-compute init [--config better-compute.config.ts]

init writes a starter better-compute.config.ts (or the JavaScript form when --config names a .mjs or .js file): a configuration factory that uses PGlite in a local .better-compute-pglite directory for development and PostgreSQL when BETTER_COMPUTE_DATABASE_URL is set, reads the secret and base URL from the environment, shows where better-iam plugs in, and exports an empty list of project commands. It never overwrites an existing file.

better-compute init
better-compute init --config better-compute.config.mjs

migrate

Create or upgrade the database schema and apply module migrations

better-compute migrate [--config PATH]

migrate runs compute.initialize(): it checks every method's IAM action against the merged catalog and the normative method table (INVALID_CONFIG on a mismatch), then creates or upgrades the compute schema and applies every module's and plugin's migrations. Run it on every deploy before the application starts; it is idempotent.

better-compute migrate
BETTER_COMPUTE_DATABASE_URL=pglite:./data better-compute migrate

doctor

Check the database, schema, clock, method registry and IAM wiring

better-compute doctor [--strict] [--pki PATH] [--config PATH]

doctor runs compute.selfCheck() (applied migrations, btree_gist, compute_now() against the database clock, the method → action registry, and each module's own checks) and adds the CLI's findings, such as a deployment with no IAM configured, the PKI bundle, and the configuration's host export (whether the gateway role can authenticate daemons by node certificate, reach the api's pokes, tunnels and revocations, and whether host routes fit beside the API). It only reads. --strict exits non-zero (DOCTOR_FINDINGS) when any error or warning is found.

better-compute doctor
better-compute doctor --strict --query "findings[].check"

version

Print the better-compute version

better-compute version

version prints the version of this command line (also --version or -v).

completion

Print a shell completion script (bash, zsh or fish)

better-compute completion SHELL

completion prints a script that completes commands, their flags and the values of flags with choices, generated from this program's commands (a configuration's project commands included). Load it in your shell's startup file.

source <(better-compute completion bash)
source <(better-compute completion zsh)
better-compute completion fish | source

serve

Run the API and the workers in this process

better-compute serve [--host HOST] [--port PORT] [--roles ROLES] [--no-migrate] [--config PATH]

serve loads the configuration, migrates (skip with --no-migrate once a deploy step runs better-compute migrate), starts the worker roles (controllers: reconcilers and the command sweeper; scheduler; sinks: outbox dispatch; iam: IAM jobs) under their leases, and serves the API with compute.nodeHandler on --host:--port. Run several processes against one database: leases and shard ownership keep each job single-writer. --roles api serves the API only; --roles controllers,sinks runs a worker with no listener; --roles gateway runs the daemon gateway over mTLS from the configuration's host.gateway (all includes it when configured), with the report hooks of the built-in modules and tunnels when the deployment issues exec tickets. Beside the API the listener answers /healthz, /readyz, /.well-known/better-compute (the server's document, with JoinService's public keys when pki.join publishes them: the fallback bcd checks against its pins) and the host export's own routes (for example GET /watch and GET /metrics). SIGINT or SIGTERM drains the gateway first, then stops the listener and the workers, releasing their leases.

better-compute serve
better-compute serve --roles api --port 8080
better-compute serve --roles controllers,sinks,iam --no-migrate
better-compute serve --roles gateway,controllers

dev

Run a local development server with no setup

better-compute dev [--host HOST] [--port PORT] [--data DIR] [--memory] [--sim N] [--sim-variant VARIANT] [--config PATH]

dev runs the API and every worker role on 127.0.0.1. With a configuration file (or BETTER_COMPUTE_DATABASE_URL) it uses that deployment; without one it keeps PGlite in --data (default .better-compute/dev-db; --memory for a throwaway database) and a generated deployment secret in .better-compute/dev-secret (owner-only), so repeated runs keep their data. It always migrates first. Without IAM configured only public methods answer; see better-compute iam setup. --sim N adds a gateway on loopback cleartext HTTP/2 (sessions authenticate by a header; local development only) and N simulated machines that join the way bcd does: a join token sealed to throwaway dev JoinService keys, the Join RPC, a Session stream, diag.nvml acceptance and adoption by the real runtime. Without configured IAM, --sim starts an embedded in-memory better-iam and prints its root token; with configured IAM it acts as BETTER_COMPUTE_TOKEN, which must be a root administrator.

better-compute dev
better-compute dev --memory --port 0
better-compute dev --memory --sim 8
better-compute dev --sim 4 --sim-variant l40s

sim

Run the deterministic fleet simulator and check its invariants

better-compute sim [--seed SEED] [--nodes N] [--duration DURATION] [--settle DURATION] [--chaos LEVEL] [--log PATH]

sim runs --nodes FakeDaemons on fake hardware against the in-memory gateway stub for --duration of simulated time, with a steady workload (diagnostics, inventory refreshes, log collection, reboots, GPU bookings) and --chaos faults (none, light, heavy: crashes, reboots, journal loss, partitions, half-open links, resets, stalls, gateway kills), then quiesces for --settle and checks invariants I1 (no double booking), I2 (at-most-once side effects), I5 (no allocation released only because its node disconnected) and I8 (usage). Nothing reads the wall clock: the same --seed prints the same digest. It exits SIM_INVARIANT_VIOLATED when an invariant fails. Needs @better-compute/testing.

better-compute sim
better-compute sim --seed nightly-42 --nodes 500 --duration 1h --chaos heavy

support bundle

Write a redacted diagnostics bundle for a support request

better-compute support bundle [--out PATH] [--pki PATH] [--config PATH]

support bundle collects what a support request about the control plane needs: the CLI, Node and platform versions; the configuration's shape (database kind, modules, whether IAM, PKI, tunnels and a notifier are configured; never URLs or values); doctor's findings; applied migrations; gateway and worker heartbeats; work-queue, command and IAM-inbox backlogs; and node counts by state. Environment variables appear by name only. Before anything is written, the bundle is scanned for join tokens (bcjt*), IAM tokens (biam*), JWTs, private keys, URL passwords and the deployment's own secrets, and each is replaced; a bundle in which a secret survives is refused (SUPPORT_BUNDLE_LEAK). The file is written owner-only. It only reads.

better-compute support bundle
better-compute support bundle --out - > bundle.json

API

api

Call any compute API method as the current token

better-compute api GROUP.METHOD [key=value ...] [--data JSON|@FILE|-] [--list] [--config PATH] [--url URL]

api calls any method of the HTTP API (the same routes, envelope and permission checks as POST {basePath}/{group}/{method}) as BETTER_COMPUTE_TOKEN, in process through the configuration or against --url, and prints the result. Public methods (system.version, system.whoami) need no token; system.whoami reports the token when one is set. Build the input with --data (JSON, @file.json, or - for standard input) and key=value items: name=gpu-a sets a string, limit:=10 or labels:='["a","b"]' sets JSON, spec:=@spec.json reads a JSON file, notes=@notes.md reads a text file, resource.type=pool nests, and ids[]=a appends. Plugin methods are plugins.ID.GROUP.METHOD. api --list [GROUP] lists every route with whether it needs a token and the IAM action it is decided on.

| Flag | Description | Default | Environment | | ----------------- | ------------------------------------------------------------------------------------------------------------- | ------- | ---------------------------------------------------- | --- | --- | | --data JSON | @FILE | - | Request body as JSON, a JSON file, or standard input | | | | --list | List routes (optionally of one group) instead of calling one | | | | --config PATH | Configuration module; default: the nearest better-compute.config.{mjs,js,ts,mts} | | BETTER_COMPUTE_CONFIG | | --url URL | Call a running compute server (https://host or https://host/api/compute) instead of loading the configuration | | BETTER_COMPUTE_URL | | --format FORMAT | Output as json (indented, default), compact (one line), or table | | | | --query PATH | Print only part of the result, e.g. protocol.max or findings[].check (strings print raw) | | |

better-compute api --list
better-compute api system.version
better-compute api system.selfCheck --query "findings[].check"
better-compute api system.whoami --url https://compute.example.com
better-compute api inventory.get tenantId=tenant-acme nodeId=node_01jz0000000000000000000000
echo '{"tenantId":"tenant-acme","widgetId":"w1"}' | better-compute api plugins.acme.widgets.get --data -

Access

auth login

Save a token for later commands (checked with system.whoami)

better-compute auth login [--profile NAME] [--no-verify] [--config PATH] [--url URL]

auth login reads an IAM session token, API key or session JWT from standard input (or BETTER_COMPUTE_TOKEN), checks it with system.whoami against the deployment (--url, or the configuration in process; --no-verify skips the check), and saves it under --profile in better-compute's credentials file (BETTER_COMPUTE_CREDENTIALS, else %APPDATA%\better-compute or ~/.config/better-compute), written owner-only. Token commands then use it when BETTER_COMPUTE_TOKEN is unset and no better-iam session is saved. A session that better-iam's own CLI saved (better-iam login) is used without this step.

better-compute auth login --url https://compute.example.com < token.txt
BETTER_COMPUTE_TOKEN=biam_key_… better-compute auth login --profile ci --no-verify

auth status

Show which credential token commands use (never the token)

better-compute auth status [--profile NAME]

auth status says where token commands get their credential, in PLAN §9.3's order: BETTER_COMPUTE_TOKEN, else better-iam's saved session (better-iam login, when @better-iam/cli is installed), else better-compute's saved profile. It lists the saved profiles without their tokens.

better-compute auth status

auth logout

Forget a saved profile's token

better-compute auth logout [--profile NAME]

auth logout removes a profile from better-compute's credentials file (the current one by default). It does not revoke the session in better-iam: run better-iam logout for that.

better-compute auth logout
better-compute auth logout --profile ci

ssh-cert

Get a break-glass SSH certificate for one node, next to your key

better-compute ssh-cert [COMMAND...] --tenant ID --node ID [--key PATH] [--account NAME] [--minutes N] [--connect HOST] [--ssh PROGRAM] [--config PATH] [--url URL]

ssh-cert asks nodes.issueSshCert for a short-lived OpenSSH user certificate for your own public key (--key, default ~/.ssh/id_ed25519.pub, else id_ecdsa.pub) and writes it beside the key as <key>-cert.pub, where ssh -i <key> finds it. The certificate is bound to the node (principal <account>@<nodeId>): it opens that node only, as --account (default root), for --minutes (default 15, at most 60, and never past your session). It needs compute:nodes:ssh-root and a session verified with MFA. The private key never leaves your machine. Revoke it early with api nodes.revokeSshCert.

better-compute ssh-cert --tenant org_acme --node node_01k5w… && ssh -i ~/.ssh/id_ed25519 root@10.0.0.5
better-compute ssh-cert --tenant org_acme --node node_01k5w… --key ./ops.pub --minutes 5
better-compute ssh-cert --node node_01k5w… --connect 10.0.0.5 -- journalctl -u bcd -n 50

console

Open an interactive console on a node, or an instance’s serial console

better-compute console --tenant ID [--node ID] [--instance ID] [--config PATH] [--url URL]

console opens a root console on one node (--node, compute:nodes:console on the node), or the serial console of one running instance (--instance, compute:instances:exec on the instance), through tunnels.open. The session runs over the server’s tunnel WebSocket, so it needs --url (or BETTER_COMPUTE_URL). The terminal is in raw mode until the remote program exits: every key, Ctrl-C included, goes to the remote, and Ctrl-] detaches. The command exits with the remote program’s status (255 when the tunnel breaks), like ssh. Tickets are single-use and the gateway and the node verify them again; revoking your session or the delegation closes the tunnel.

better-compute console --url https://compute.example.com --tenant org_acme --node node_01k5w…
better-compute console --url https://compute.example.com --tenant org_acme --instance inst_01k5w…

exec

Open an interactive shell in a running instance

better-compute exec --tenant ID --instance ID [--config PATH] [--url URL]

exec opens a shell in one running instance through tunnels.open (compute:instances:exec on the instance); its node's agent runs it. The session runs over the server’s tunnel WebSocket, so it needs --url (or BETTER_COMPUTE_URL). The terminal is in raw mode until the remote program exits: every key, Ctrl-C included, goes to the remote, and Ctrl-] detaches. The command exits with the remote program’s status (255 when the tunnel breaks), like ssh. Tickets are single-use and the gateway and the node verify them again; revoking your session or the delegation closes the tunnel.

better-compute exec --url https://compute.example.com --tenant org_acme --instance inst_01k5w…

forward

Forward a local port to a port of a running instance

better-compute forward --tenant ID --instance ID --port PORT [--local-port PORT] [--bind HOST] [--config PATH] [--url URL]

forward listens on --bind (default 127.0.0.1) at --local-port (default: the same as --port; 0 picks a free one) and forwards each connection to --port on the instance through its own tcp tunnel (tunnels.open, compute:instances:exec on the instance), like ssh -L. It runs until Ctrl-C. The tunnels run over the server’s WebSocket, so it needs --url (or BETTER_COMPUTE_URL). A connection is re-authorized like any tunnel: revoking your session or the delegation closes it. Binding anything but loopback lets whoever reaches that address use your access; even on loopback, other users of this machine and web pages open in your browser can reach the port, as with ssh -L. At most 16 connections are forwarded at once, and new ones are refused while the server rate-limits your tunnels.

better-compute forward --url https://compute.example.com --tenant org_acme --instance inst_01k5w… --port 5432
better-compute forward --instance inst_01k5w… --port 8888 --local-port 0

Capacity

reserve

Reserve GPUs from a pool (reservations.create)

better-compute reserve --tenant ID --pool ID --gpus N --for DURATION [--selector EXPR] [--model MODEL] [--product PRODUCT] [--nvlink] [--project ID] [--start TIME] [--lease SECONDS] [--key KEY] [--wait SECONDS] [--cpus N] [--memory GIB] [--kubernetes] [--config PATH] [--url URL]

reserve asks for --gpus whole GPUs from --pool for --for, decided by better-iam as compute:reservations:create on the reservation draft and placed by the pool's placer (PLAN.md §3.4, §10.3). --selector takes the shorthand gpuProduct in (H100-SXM5-80GB), vramGiB >= 80; --model and --product add a gpuModel or gpuProduct match. It waits up to --wait seconds for the placement and prints the reservation, whose binding lists the booked GPU UUIDs once active. Every run sends a new idempotency key unless --key is given: repeat the command with the same --key to retry safely.

better-compute reserve --pool pool_01k… --gpus 4 --for 8h
better-compute reserve --pool pool_01k… --gpus 2 --for 8h --cpus 32 --memory 256 --kubernetes
better-compute reserve --pool pool_01k… --gpus 8 --for 3d --model H100 --nvlink --selector "vramGiB >= 80"
better-compute reserve --pool pool_01k… --gpus 2 --for 1h --start +2h --key nightly-2026-09-24

release

Release a reservation early (reservations.release)

better-compute release RESERVATION --tenant ID [--cancel] [--config PATH] [--url URL]

release ends an active or placed reservation now: its bookings are truncated, the GPUs return to the pool and billing stops at the release time. A reservation that has not started yet can be withdrawn with --cancel instead (reservations.cancel).

better-compute release rsv_01k…
better-compute release rsv_01k… --cancel

extend

Extend a reservation (reservations.extend)

better-compute extend RESERVATION --tenant ID [--by DURATION] [--until TIME] [--renew] [--key KEY] [--config PATH] [--url URL]

extend moves the end of a reservation later, by --by or to --until. It is admitted like a new reservation: better-iam decides compute:reservations:extend on the total duration after the change, so policy caps also bound extensions, and the booking must still be free. With --renew it instead renews a leased reservation (reservations.renew).

better-compute extend rsv_01k… --by 4h
better-compute extend rsv_01k… --renew

reservations list

List the tenant’s reservations (reservations.list)

better-compute reservations list --tenant ID [--state STATE] [--pool ID] [--limit N] [--cursor ID] [--config PATH] [--url URL]

List the tenant’s reservations (reservations.list)

better-compute reservations list --state active
better-compute reservations list --format json

reservations get

Show one reservation, with its binding (reservations.get)

better-compute reservations get RESERVATION --tenant ID [--config PATH] [--url URL]

Show one reservation, with its binding (reservations.get)

better-compute reservations get rsv_01k… --query binding

pools list

List the pools the tenant owns or is offered (pools.list)

better-compute pools list --tenant ID [--config PATH] [--url URL]

List the pools the tenant owns or is offered (pools.list)

better-compute pools list

capacity

Show free and allocated capacity: a summary, or one pool (capacity.summary, capacity.byPool)

better-compute capacity --tenant ID [--pool ID] [--preview] [--gpus N] [--for DURATION] [--selector EXPR] [--cpus N] [--memory GIB] [--kubernetes] [--config PATH] [--url URL]

capacity prints what the tenant can see: per pool and per GPU model, total, allocatable, allocated, reserved and available. With --pool it prints that pool's rollup. With --preview and a --gpus request it asks where such a reservation would fit right now (capacity.preview) without booking anything.

better-compute capacity
better-compute capacity --pool pool_01k…
better-compute capacity --preview --pool pool_01k… --gpus 8 --for 1d --selector "vramGiB >= 80"

Sandboxes

sandbox create

Create a sandbox from a template (sandboxes.create)

better-compute sandbox create --tenant ID --template ID [--ttl DURATION] [--from-snapshot ID] [--wait SECONDS] [--key KEY] [--config PATH] [--url URL]

sandbox create starts a sandbox from --template (sbxt_…), claimed from the template's warm pool when it keeps one, decided by better-iam as compute:sandboxes:create. It lives --ttl (default: the template's default, at most its maximum) and is deleted then unless extended. --from-snapshot restores a snapshot of yours instead of booting the image. It waits up to --wait seconds (default 30) for the sandbox to leave starting and prints it. Every run sends a new idempotency key unless --key is given: repeat with the same --key to retry safely.

better-compute sandbox create --template sbxt_01k5w… --ttl 30m
better-compute sandbox create --template sbxt_01k5w… --from-snapshot snap_01k5w…

sandbox list

List sandboxes: yours, or the tenant’s with --all (sandboxes.list)

better-compute sandbox list --tenant ID [--all] [--deleted] [--template ID] [--limit N] [--cursor CURSOR] [--config PATH] [--url URL]

List sandboxes: yours, or the tenant’s with --all (sandboxes.list)

better-compute sandbox list
better-compute sandbox list --all --query "items[*].id"

sandbox get

Show a sandbox, its expiry and its snapshots (sandboxes.get)

better-compute sandbox get SANDBOX --tenant ID [--config PATH] [--url URL]

Show a sandbox, its expiry and its snapshots (sandboxes.get)

better-compute sandbox get sbx_01k5w…

sandbox extend

Move a sandbox’s expiry (sandboxes.extend)

better-compute sandbox extend SANDBOX --tenant ID [--by DURATION] [--until TIME] [--config PATH] [--url URL]

sandbox extend adds --by to the current expiry, or sets it to --until (ISO 8601, epoch ms or +DURATION from now), within the template's maximum lifetime. Decided as compute:sandboxes:update on the sandbox.

better-compute sandbox extend sbx_01k5w… --by 30m
better-compute sandbox extend sbx_01k5w… --until +2h

sandbox snapshot

Snapshot a sandbox, memory included unless --no-memory (sandboxes.snapshot)

better-compute sandbox snapshot SANDBOX --tenant ID [--no-memory] [--keep] [--key KEY] [--config PATH] [--url URL]

sandbox snapshot asks the sandbox's host for its instance's state; the snapshot is pending until the host reports it. Snapshots go with the sandbox unless --keep. Restore one with sandbox create --from-snapshot.

better-compute sandbox snapshot sbx_01k5w… --keep

sandbox delete

Delete a sandbox now (sandboxes.delete)

better-compute sandbox delete SANDBOX --tenant ID [--config PATH] [--url URL]

Delete a sandbox now (sandboxes.delete)

better-compute sandbox delete sbx_01k5w…

sandbox exec

Run a command (or a shell) in a sandbox over SSH through a tunnel (sandboxes.exec)

better-compute sandbox exec SANDBOX [COMMAND...] --tenant ID [--key PATH] [--minutes N] [--ssh PROGRAM] [--accept-host-key] [--config PATH] [--url URL]

sandbox exec asks sandboxes.exec for a short-lived SSH certificate for your own key (--key, default ~/.ssh/id_ed25519; its .pub is sent, the private key never leaves this machine) and a single-use tunnel ticket to the sandbox's instance, then runs your OpenSSH client (--ssh, default ssh) through that tunnel: the command after --, or a login shell. There is no agent in the guest; its sshd trusts the sandbox CA for <account>@<instance>. The certificate and a known_hosts file for this one connection live in a temporary directory that is removed afterwards. It exits with ssh's status. Needs --url (tunnels run over the server's WebSocket) and a signed-in session.

better-compute sandbox exec sbx_01k5w… -- uname -a
better-compute sandbox exec sbx_01k5w…

sandbox-template create

Create a sandbox template for the tenant (sandboxTemplates.create)

better-compute sandbox-template create --tenant ID --name NAME --pool ID [--runtime ID] [--flavor NAME] [--image ID] [--user-data FILE] [--default-ttl DURATION] [--max-ttl DURATION] [--warm-min N] [--warm-max N] [--env NAME=REF,…] [--network MODE] [--volumes NAME:/PATH[:ro],…] [--config PATH] [--url URL]

sandbox-template create defines what sandbox create --template starts: --pool, --flavor and --image (and the pool's --runtime), the default and longest lifetimes, a warm pool kept ready (--warm-min/--warm-max), user data from a file, environment variables from secret references and the network mode. Decided as compute:sandboxes:manage on the tenant.

better-compute sandbox-template create --name python --pool pool_01k5w… --flavor small --image img_01k5w… --warm-min 2 --max-ttl 4h

sandbox-template update

Change a sandbox template (sandboxTemplates.update)

better-compute sandbox-template update TEMPLATE --tenant ID [--flavor NAME] [--image ID] [--user-data FILE] [--default-ttl DURATION] [--max-ttl DURATION] [--warm-min N] [--warm-max N] [--env NAME=REF,…] [--network MODE] [--volumes NAME:/PATH[:ro],…] [--no-user-data] [--config PATH] [--url URL]

sandbox-template update changes only the fields given; --no-user-data removes the user data. Sandboxes already running keep what they started with; the warm pool is refilled from the new definition.

better-compute sandbox-template update sbxt_01k5w… --warm-min 4 --image img_01k5w…

sandbox-template delete

Delete a sandbox template (sandboxTemplates.delete)

better-compute sandbox-template delete TEMPLATE --tenant ID [--config PATH] [--url URL]

Delete a sandbox template (sandboxTemplates.delete)

better-compute sandbox-template delete sbxt_01k5w…

sandbox templates

List the tenant’s sandbox templates and their warm pools (sandboxTemplates.list)

better-compute sandbox templates --tenant ID [--config PATH] [--url URL]

List the tenant’s sandbox templates and their warm pools (sandboxTemplates.list)

better-compute sandbox templates --format table

sandbox-volume create

Create a persistent volume (agent memory) on a pool (sandboxVolumes.create)

better-compute sandbox-volume create --tenant ID --pool ID --name NAME --size GIB [--key KEY] [--config PATH] [--url URL]

sandbox-volume create books --size GiB of disk on one host of --pool; sandboxes of templates that mount it (sandbox-template --volumes) run on that host and keep its data across runs. It is billed until deleted. Repeat with the same --key to retry safely.

better-compute sandbox-volume create --pool pool_01k5w… --name agent-notes --size 20

sandbox-volume list

List the tenant’s persistent volumes (sandboxVolumes.list)

better-compute sandbox-volume list --tenant ID [--pool ID] [--deleted] [--all] [--config PATH] [--url URL]

List the tenant’s persistent volumes (sandboxVolumes.list)

better-compute sandbox-volume list --format table

sandbox-volume get

Show a persistent volume (sandboxVolumes.get)

better-compute sandbox-volume get VOLUME --tenant ID [--config PATH] [--url URL]

Show a persistent volume (sandboxVolumes.get)

better-compute sandbox-volume get vol_01k5w…

sandbox-volume resize

Grow a persistent volume (sandboxVolumes.resize)

better-compute sandbox-volume resize VOLUME --tenant ID --size GIB [--config PATH] [--url URL]

sandbox-volume resize grows the volume to --size GiB; volumes never shrink.

better-compute sandbox-volume resize vol_01k5w… --size 40

sandbox-volume delete

Delete a persistent volume and wipe its data (sandboxVolumes.delete)

better-compute sandbox-volume delete VOLUME --tenant ID [--config PATH] [--url URL]

Delete a persistent volume and wipe its data (sandboxVolumes.delete)

better-compute sandbox-volume delete vol_01k5w…

sandbox-snapshot list

List sandbox snapshots, kept ones of deleted sandboxes too (sandboxSnapshots.list)

better-compute sandbox-snapshot list --tenant ID [--all] [--sandbox ID] [--limit N] [--cursor CURSOR] [--config PATH] [--url URL]

List sandbox snapshots, kept ones of deleted sandboxes too (sandboxSnapshots.list)

better-compute sandbox-snapshot list --sandbox sbx_01k5w…

sandbox-snapshot get

Show a sandbox snapshot and its state (sandboxSnapshots.get)

better-compute sandbox-snapshot get SNAPSHOT --tenant ID [--config PATH] [--url URL]

Show a sandbox snapshot and its state (sandboxSnapshots.get)

better-compute sandbox-snapshot get snap_01k5w…

sandbox-snapshot delete

Delete a sandbox snapshot (sandboxSnapshots.delete)

better-compute sandbox-snapshot delete SNAPSHOT --tenant ID [--config PATH] [--url URL]

Delete a sandbox snapshot (sandboxSnapshots.delete)

better-compute sandbox-snapshot delete snap_01k5w…

Nodes

nodes list

List the tenant’s nodes (nodes.list)

better-compute nodes list --tenant ID [--pool ID] [--site ID] [--cordoned] [--state STATE] [--limit N] [--cursor CURSOR] [--config PATH] [--url URL]

List the tenant’s nodes (nodes.list)

better-compute nodes list --pool h100-eu
better-compute nodes list --cordoned --format json

nodes get

Show one node: its state, labels, conditions and session (nodes.get)

better-compute nodes get NODE --tenant ID [--config PATH] [--url URL]

Show one node: its state, labels, conditions and session (nodes.get)

better-compute nodes get node_01k5w…
better-compute nodes get node_01k5w… --query conditions

nodes events

List a node’s events, newest first (nodes.events)

better-compute nodes events NODE --tenant ID [--type TYPE] [--limit N] [--cursor CURSOR] [--config PATH] [--url URL]

List a node’s events, newest first (nodes.events)

better-compute nodes events node_01k5w… --type gpu.xid

nodes cordon

Stop placing new work on a node (nodes.cordon)

better-compute nodes cordon NODE --tenant ID [--reason TEXT] [--if-version N] [--config PATH] [--url URL]

nodes cordon keeps the scheduler from placing anything new on the node; what runs there keeps running. Decided as compute:nodes:cordon. --if-version makes it conditional on the version nodes get printed.

better-compute nodes cordon node_01k5w… --reason "disk replacement"

nodes uncordon

Let the scheduler place work on a node again (nodes.uncordon)

better-compute nodes uncordon NODE --tenant ID [--reason TEXT] [--if-version N] [--config PATH] [--url URL]

nodes uncordon undoes nodes cordon. Decided as compute:nodes:cordon.

better-compute nodes uncordon node_01k5w… --reason "disk replacement"

nodes drain

Cordon a node and move its work off (nodes.drain)

better-compute nodes drain NODE --tenant ID [--reason TEXT] [--if-version N] [--config PATH] [--url URL]

nodes drain cordons the node and hands its allocations to the Drain controller, which releases them within the pool’s disruption budget. Decided as compute:nodes:drain; follow it with nodes events (node.draining, then the releases).

better-compute nodes drain node_01k5w… --reason "disk replacement"

nodes label

Set or remove a node’s labels (nodes.label)

better-compute nodes label NODE --tenant ID [--set KEY=VALUE,…] [--remove KEY,…] [--if-version N] [--config PATH] [--url URL]

nodes label sets labels from --set KEY=VALUE,… and removes the keys in --remove KEY,…; selectors (reservations, pools) match on them. Decided as compute:nodes:update.

better-compute nodes label node_01k5w… --set rack=r12,fabric=ib-a --remove old

nodes taint

Add or remove a node’s taints (nodes.taint)

better-compute nodes taint NODE --tenant ID [--add TAINT,…] [--remove TAINT,…] [--if-version N] [--config PATH] [--url URL]

nodes taint adds the taints in --add and removes those in --remove (comma-separated). A taint joins the node’s NoSchedule reasons as taint:<taint>, so the scheduler places nothing new there until it is removed. Decided as compute:nodes:update.

better-compute nodes taint node_01k5w… --add gpu=degraded:NoSchedule

nodes delete

Remove a retired or cordoned adopted node for good (nodes.delete)

better-compute nodes delete NODE --tenant ID [--reason TEXT] [--if-version N] [--yes] [--config PATH] [--url URL]

nodes delete tombstones a node that is retired, a cordoned adopted node (cordon it first), or one that never got past adoption or enrollment, once it holds no allocation. Its certificates are revoked and its hardware key and attestor bindings (e.g. a TPM) are freed, so the machine can join again as a new node: after a TPM swap, cordon, delete, then run bcd join --reset --yes and bcd join on the machine. It cannot be undone, so it needs --yes. Decided as compute:nodes:delete.

better-compute nodes delete node_01k5w… --reason "TPM replaced" --yes

join-tokens create

Create a join token for a pool: what bcd join presents (joinTokens.create)

better-compute join-tokens create --tenant ID --pool ID --ttl DURATION [--max-uses N] [--allow-reclaim] [--hosted WHERE] [--expect-product-uuid UUID] [--expect-serial SERIAL] [--expect-mac MAC] [--expect-gpu-uuid GPU-…] [--out PATH] [--key KEY] [--config PATH] [--url URL]

join-tokens create mints a token that lets up to --max-uses machines (default 1) join --pool for --ttl (60s to 24h). --expect-* bind it to one machine's identity (product UUID, serial, MAC or GPU UUID). --hosted kubernetes marks it for bcd as a DaemonSet (deploy/kubernetes): the cluster's admins have root on its machines, so they join tenant-controlled unless the pool's policy.kubernetes.platformOperated is true. The token is printed once and never again: with --out it goes to a new file (0600, never overwritten) instead of the output, to hand to the server out of band (the install script reads BCD_JOIN_TOKEN or stdin). Decided as compute:join-tokens:create.

better-compute join-tokens create --pool h100-eu --ttl 2h --max-uses 8 --out ./join-token
better-compute join-tokens create --pool h100-eu --ttl 30m --expect-serial SN12345
better-compute join-tokens create --pool k8s-gpu --ttl 2h --max-uses 16 --hosted kubernetes --out ./join-token

join-tokens list

List a pool’s join tokens, never their secrets (joinTokens.list)

better-compute join-tokens list --tenant ID --pool ID [--all] [--limit N] [--cursor CURSOR] [--config PATH] [--url URL]

List a pool’s join tokens, never their secrets (joinTokens.list)

better-compute join-tokens list --pool h100-eu

join-tokens revoke

Revoke a join token before it expires (joinTokens.revoke)

better-compute join-tokens revoke TOKEN --tenant ID --pool ID [--config PATH] [--url URL]

Revoke a join token before it expires (joinTokens.revoke)

better-compute join-tokens revoke jt_01k5w… --pool h100-eu

join-requests list

List a pool’s join requests, pending by default (joinRequests.list)

better-compute join-requests list --tenant ID --pool ID [--state STATE] [--limit N] [--cursor CURSOR] [--config PATH] [--url URL]

List a pool’s join requests, pending by default (joinRequests.list)

better-compute join-requests list --pool h100-eu

join-requests approve

Let a machine that asked join the pool (joinRequests.approve)

better-compute join-requests approve REQUEST --tenant ID --pool ID [--reason TEXT] [--ttl SECONDS] [--config PATH] [--url URL]

join-requests approve admits the machine behind the request into --pool; the approval waits --ttl seconds (default 3600) for the machine to retry. Check its claims (join-requests list) first: approving is what makes an unknown machine a node. Decided as compute:join-tokens:create.

better-compute join-requests approve jreq_01k5w… --pool h100-eu

join-requests reject

Turn a machine’s join request down (joinRequests.reject)

better-compute join-requests reject REQUEST --tenant ID --pool ID [--reason TEXT] [--config PATH] [--url URL]

Turn a machine’s join request down (joinRequests.reject)

better-compute join-requests reject jreq_01k5w… --pool h100-eu

inventory get

Show a node’s current hardware inventory (inventory.get)

better-compute inventory get NODE --tenant ID [--config PATH] [--url URL]

Show a node’s current hardware inventory (inventory.get)

better-compute inventory get node_01k5w… --query gpus

inventory history

List a node’s inventory snapshots, newest first (inventory.history)

better-compute inventory history NODE --tenant ID [--limit N] [--cursor CURSOR] [--config PATH] [--url URL]

List a node’s inventory snapshots, newest first (inventory.history)

better-compute inventory history node_01k5w…

inventory diff

Show what changed in a node’s hardware between two snapshots (inventory.diff)

better-compute inventory diff NODE --tenant ID [--from SNAPSHOT] [--to SNAPSHOT] [--config PATH] [--url URL]

inventory diff compares --from and --to (snapshot ids from inventory history, or inventory digests). Without --to it is the latest snapshot, without --from the one before --to.

better-compute inventory diff node_01k5w…

site-tokens create

Create a token a site agent joins a site with (siteTokens.create)

better-compute site-tokens create --tenant ID --site ID --ttl SECONDS [--max-uses N] [--out PATH] [--key KEY] [--config PATH] [--url URL]

site-tokens create mints a token for up to --max-uses site agents (default 1) to join --site within --ttl seconds. It is printed once: with --out it goes to a new 0600 file instead. Decided as compute:sites:manage.

better-compute site-tokens create --site site_01k5w… --ttl 3600 --out ./site-token

site-tokens revoke

Revoke a site token (siteTokens.revoke)

better-compute site-tokens revoke TOKEN --tenant ID --site ID [--config PATH] [--url URL]

Revoke a site token (siteTokens.revoke)

better-compute site-tokens revoke jt_01k5w… --site site_01k5w…

Instances

instances list

List instances: yours, or the tenant’s with --all (instances.list)

better-compute instances list --tenant ID [--all] [--state STATE] [--pool ID] [--limit N] [--cursor CURSOR] [--config PATH] [--url URL]

List instances: yours, or the tenant’s with --all (instances.list)

better-compute instances list
better-compute instances list --all --state running

instances get

Show one instance (instances.get)

better-compute instances get INSTANCE --tenant ID [--config PATH] [--url URL]

Show one instance (instances.get)

better-compute instances get inst_01k5w…

instances create

Create an instance in a pool (instances.create)

better-compute instances create --tenant ID --pool ID --flavor NAME --image ID [--project ID] [--ssh-key PATH,…] [--user-data FILE|secret://…] [--stopped] [--wait SECONDS] [--key KEY] [--config PATH] [--url URL]

instances create boots --image with --flavor in --pool, decided as compute:instances:create. --ssh-key reads OpenSSH public keys from files (comma-separated paths; every non-empty line is a key), --user-data cloud-init from a file, or a secret://<tenant>/<id> reference. --stopped creates it without starting it. It waits up to --wait seconds (default 30) for the instance to settle. Every run sends a new idempotency key unless --key is given: repeat with the same --key to retry safely.

| Flag | Description | Default | Environment | | ------------------ | ------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ----------------------- | --- | | --tenant ID | The tenant acting (the caller’s organization) | | BETTER_COMPUTE_TENANT | | --pool ID | The pool | | | | --flavor NAME | The flavor (the pool offers it) | | | | --image ID | The image to boot | | | | --project ID | The project it belongs to | | | | --ssh-key PATH,… | Files of OpenSSH public keys to authorize | | | | --user-data FILE | secret://… | cloud-init user data (at most 32 KiB) | | | | --stopped | Create it stopped | | | | --wait SECONDS | Wait this long for it to settle | 30 | | | --key KEY | Idempotency key, to retry the same request | | | | --config PATH | Configuration module; default: the nearest better-compute.config.{mjs,js,ts,mts} | | BETTER_COMPUTE_CONFIG | | --url URL | Call a running compute server (https://host or https://host/api/compute) instead of loading the configuration | | BETTER_COMPUTE_URL | | --format FORMAT | Output as json (indented, default), compact (one line), or table | | | | --query PATH | Print only part of the result, e.g. protocol.max or findings[].check (strings print raw) | | |

better-compute instances create --pool vps-eu --flavor g1.small --image img_01k5w… --ssh-key ~/.ssh/id_ed25519.pub

instances start

Start a stopped instance (instances.start)

better-compute instances start INSTANCE --tenant ID [--config PATH] [--url URL]

Start a stopped instance (instances.start)

better-compute instances start inst_01k5w…

instances stop

Stop a running instance (instances.stop)

better-compute instances stop INSTANCE --tenant ID [--config PATH] [--url URL]

Stop a running instance (instances.stop)

better-compute instances stop inst_01k5w…

instances delete

Delete an instance and its disks (instances.delete)

better-compute instances delete INSTANCE --tenant ID [--config PATH] [--url URL]

Delete an instance and its disks (instances.delete)

better-compute instances delete inst_01k5w…

instances resize

Move an instance to another flavor (instances.resize)

better-compute instances resize INSTANCE --tenant ID --flavor NAME [--config PATH] [--url URL]

Move an instance to another flavor (instances.resize)

better-compute instances resize inst_01k5w… --flavor g1.large

Events

events list

List the tenant’s events, newest first (events.list)

better-compute events list --tenant ID [--type TYPE] [--limit N] [--cursor CURSOR] [--config PATH] [--url URL]

List the tenant’s events, newest first (events.list)

better-compute events list --type node.draining
better-compute events list --query "items[*].type"

events watch

Follow the tenant’s events as they happen, one JSON line each (GET /watch)

better-compute events watch --tenant ID [--types PATTERN,…] [--since CURSOR] [--count N] [--path PATH] [--config PATH] [--url URL]

events watch follows the host's server-sent events route (--path, default /watch; the console app serves /api/compute/watch) as BETTER_COMPUTE_TOKEN, so it needs --url. Each event is printed as one line of JSON with its sequence, the cursor: pass the last one to --since to resume where a previous run stopped. It reconnects after a broken connection, resuming from the last event, until Ctrl-C, --count events, or a refusal: a revoked session or a withdrawn compute:events:read ends it.

better-compute events watch --url https://compute.example.com --types "node.*,reservation.*"
better-compute events watch --url https://compute.example.com --since 184467.12 --count 100

Operations

releases register

Register a signed bcd release manifest for rollouts (releases.register)

better-compute releases register MANIFEST --tenant ID [--config PATH] [--url URL]

releases register sends a published manifest.json ({ manifest, signatures }) as it is; the server checks the signatures against its release keys. Decided as compute:fleet:admin.

better-compute releases register ./dist/manifest.json

releases list

List the registered bcd releases (releases.list)

better-compute releases list --tenant ID [--config PATH] [--url URL]

List the registered bcd releases (releases.list)