- Commands that create or select print the resulting ID as their only stdout. Progress and diagnostics go to stderr. Agents capture stdout and never parse prose.
execandlogspass the remote exit code through verbatim.- Read commands take
--json. - Destructive commands don’t confirm (
rm,stop); creation is idempotent (retrying a failedmakecannot double-launch).
Boxes
tesser make [service] [--ensure-running <sha>]
Creates a box, claiming a warm-pool blank when one is available (seconds)
and cold-launching otherwise. Prints the box_… ID.
- No service argument → a workbench: the current worktree synced to
a box, nothing serving. The default target for
exec. - With a service (or a manifest path) → an instance box for that service. The service is a birth parameter; a repo with multiple manifests must name one — ambiguity is a loud error listing the options.
--ensure-running <sha>→ a pinned instance: idempotent — if that (service, sha) already runs, prints its existing box ID and exits. Content is materialized locally as a standalone shallow clone at the sha and pushed;setupthendevrun from the manifest; readiness gates on the health check; a prior pinned instance of the service is replaced blue/green (alias flips atomically, old box drains, then is removed).
tesser ls [--json] / tesser status <box_id> [--json]
Boxes with class, service, power state, and activity. The recovery path
when an agent loses an ID — cells are authoritative and EC2 tags stay
legible, so ls is always trustworthy.
tesser rm <box_id>
The box ceases to exist: disk, instance, mesh registration, overrides
referencing it. Unrecoverable. Never asks for confirmation.
tesser sleep <box_id>
Powers the box down; ID, private IP, and disk persist. Rarely needed by
hand — the reaper sleeps idle boxes (instance boxes at 2h, workbenches at
10m) and removes boxes asleep 16h. There is no wake command: any
operation targeting a sleeping box wakes it transparently, re-running the
dev recipe on instance boxes.
Code and commands
tesser sync <box_id> [--restart] [--force]
Mirrors the current worktree to the box. Unchanged trees short-circuit on a
fingerprint; a sync that would delete most of the remote tree aborts (wrong
worktree?) unless --force. --restart re-runs the dev recipe after an
effective sync and waits for health — for changes the server can’t
hot-absorb; the agent decides when. exec and dev sync implicitly first.
tesser exec [box_id] [--in <service>] [--deps-of <service>] -- <cmd…>
Runs a command in the synced workspace and streams stdio; the remote exit
code is the local exit code.
- With no box ID, targets the worktree’s workbench, creating one on first use — tests and typechecks never contend with a dev server.
--in <service>runs in that service’srootdirectory.--deps-of <service>applies that service’s[deps]bindings to the workbench for the duration — integration tests reachlocalhost:5432exactly as the service would.
tesser dev <service|box_id> [--force] -- [cmd…]
Starts (or replaces) the dev instance for a service from the current
worktree: creates or reuses the (worktree, service) box, syncs, runs
setup if needed, ensures the manifest’s deps (ensure-on-use — pinned
deps start or wake as required), runs the dev recipe, waits for health,
wires the cohort, registers the viewport target. Prints the box ID.
Re-running replaces the server — that is also the crash-recovery path. An
explicit trailing command overrides the manifest’s dev recipe.
tesser logs <box_id> [-f]
Tails the instance’s log over SSH — last 200 lines, or follow. Logs live on
the box; nothing streams through the control plane.
tesser stop <box_id>
Stops the running instance (process level). The box stays awake; the mesh
deregisters the instance. Distinct from sleep (power) and rm
(existence).
Mesh and viewport
tesser use <box_id|name>
Points the default viewport (localhost:3000) at a target. The panel
injected into proxied pages and the widget are the primary switching
surface; use is the scriptable form. Any box is also always directly
addressable at <boxid>.localhost:<port> — Host-routed, no selection
involved.
Per-name mesh overrides (“this box’s backend goes to my backend”) are
written through the panel or use-style commands and stored per box;
cohort auto-wiring covers the common case without any command at all.
tesser env set <service> KEY=VALUE… / tesser env ls <service>
Sets control-plane-held env values for a service. ensure-running fails
loudly if a manifest’s env.required names are unset. Values never live in
the repo.
Fleet
tesser pool fill [N] / pool ls / pool drain
Maintains machine-warm blanks for instant claims. Unclaimed pool boxes
self-destruct on a timer.
tesser daemon
Runs tesserd: the viewport proxy and Host router, SSH tunnels, laptop dep
bindings, and the switcher widget/panel APIs.