Use mocactl
Install and run it​
New here? Set up mocactl against the Compose trial goes from nothing to a streamed reply on the Docker Compose trial.
Install (macOS or Linux, Node.js 22 or later):
curl -fsSL https://raw.githubusercontent.com/rossoctl/moca/main/scripts/install-mocactl.sh | sh
export SH_CONTROL_PLANE_URL=https://moca.example.com # your moca server; the only URL mocactl needs
mocactl # interactive; the first run walks you through setup
mocactl --setup # re-run setup on a configured machine
It installs ~/.local/bin/mocactl (a symlink to mocactl.mjs beside it) from the latest release, after checking its SHA-256, and prints
the PATH line to add if that directory isn't on your PATH yet. Re-run it to upgrade.
MOCACTL_VERSION=edge installs the build of main, MOCACTL_VERSION=v0.6.0 a given release, and
MOCACTL_INSTALL_DIR sets another directory. mocactl --version says which one you have. To
uninstall, rm ~/.local/bin/mocactl ~/.local/bin/mocactl.mjs (and ~/.config/mocactl for its config and login).
From a checkout (contributors): pnpm install, then node packages/mocactl/bin/mocactl.mjs,
which runs the TypeScript sources directly. pnpm --filter @moca/mocactl build writes the
release bundle to packages/mocactl/dist/mocactl.mjs.
mocactl needs one URL: the server's (the control plane). It comes from --control-plane-url, then
SH_CONTROL_PLANE_URL, then the saved config. The control plane says where the harness is
(GET /v1/discovery, set by its operator with SH_PUBLIC_HARNESS_URL), so there is nothing else to
configure. Onboarding checks the control plane and the harness it points at before saving the URL —
nothing is written to disk until both answer.
--harness-url / SH_HARNESS_URL override discovery (e.g. a harness behind a local port-forward);
onboarding never saves a discovered harness URL, so a harness the operator moves is followed.
Keys​
| Action | Slash | Keys |
|---|---|---|
| Command palette | — | ctrl+p |
| Sessions (resume, rename, delete) | /sessions, /resume | ctrl+x l |
| New session | /new | ctrl+x n |
| Rename session | /rename <title> | ctrl+x r |
| Promote skills for the next session | /promote DIR | — |
| Drop the pending promoted bundle | /promote --clear | — |
| Credentials | /credentials | ctrl+x k |
| Toggle tool details / thinking | /details, /thinking | ctrl+x d, ctrl+x t |
| Copy last reply / export to Markdown | /copy, /export | ctrl+x y, ctrl+x x |
Compose in $EDITOR | /editor | ctrl+x e |
| Theme, diagnostics | /theme, /doctor | — |
| Help | /help | ? on an empty input |
| Quit | /quit | ctrl+x q, ctrl+c |
Enter sends, alt+enter adds a newline, ↑/↓ walk your prompt history. Esc closes any
overlay (including a loading or error screen) and, on the chat view, cancels the running turn; a
second Esc within a second also clears queued messages (after a cancel, the next queued message
waits that second before it is sent). $EDITOR (or $VISUAL) runs with the
terminal suspended — if it cannot start, a toast says so and your draft is unchanged. It runs
without a shell: the value is split into words (quotes work, e.g. code --wait or
"/path/with spaces/subl" -w), but nothing is expanded, so write $HOME/bin/ed out in full, and
on Windows name an .exe. Override
keys in config.json under keybinds, e.g. { "session.new": "ctrl+x s" }.
Headless​
mocactl login # device-flow login: prints the code; in a local terminal also copies it and opens the browser (--no-browser: don't)
mocactl logout [--all] # end this login on the server (--all: all of yours)
mocactl auth token [--json] # a valid API token for scripts and the Claude Code hook
mocactl doctor [--json] # seven checks, one fix per failure; exit 1 on failure
mocactl run "prompt" [--session ID | --new] [--option inferenceCredential=NAME] [--json]
mocactl promote DIR [--dry-run] [--json] # upload DIR's .claude/skills and .claude/commands
mocactl run "prompt" --config DIGEST # start the new session with that config bundle
mocactl run "prompt" --show-tools # print each tool call between the turn's text
mocactl run "prompt" --record F # one redacted NDJSON line per HTTP attempt to F (no token, host or text)
mocactl bundles list [--json] # your own live bundles, newest first; prints the full digest
mocactl bundles delete DIGEST [--json] # delete a bundle you promoted; frees your budget
mocactl sessions [--json] # every session you own, all pages
mocactl sessions delete ID [--json] # also drops its local history, even if already gone
mocactl credentials [--json] # names, kinds, hosts and endpoints; never secrets
printf %s "$KEY" | mocactl credentials add NAME --host HOST [--host HOST ...] \
[--kind KIND] [--consumer CONSUMER] [--endpoint URL] [--json]
mocactl credentials delete NAME [--json] # exit 1 if you own no credential of that name
Preview.
mocactl spawn,mocactl subagents,mocactl watchandmocactl getare implemented but not yet declared Stable; flags, ledger format, and output shapes may change. One follow-up is still tracked under the subagent commands issue:approve/rejectfor a subagent that stops at a gate.
mocactl spawn "prompt" [--config sha256:…] --kind prompt|solve \
[--repo URL --ref REF] [--tag T] [--label L] [--json] # fork a detached subagent; prints its sessionId
mocactl spawn --prompt-file FILE [--kind prompt|solve] [...] # read the prompt from FILE instead of argv
mocactl subagents [--tag T] [--json] # list spawned subagents + current honest state
mocactl watch [--tag T] [--json] # one line per state change, until all are finished
mocactl get SESSIONID [--out DIR] [--json] # write result files + bounded summary
mocactl spawn "prompt" --kind prompt --workload ID [--writable] [...] # run it on a workload's context
mocactl workloads create --context FILE [--name NAME] [--json] # upload a context; prints its id
mocactl workloads create --context FILE --sandboxes N [--mount read-only|writable] # with sandboxes of its own
mocactl workloads list [--json] # your own live workloads, newest first
mocactl workloads get ID [--json] # status, context type, size and frozen revision
mocactl workloads delete ID [--json] # delete the workload and its context (idempotent)
workloads delete on a workload that is already deleted exits 0 and says so, the way
kubectl delete does, so a cleanup script can delete every id it knows without telling "already
done" from a real failure. An id the harness knows nothing about still exits 1 — that one may be a
typo. With --json, the already-deleted case adds "alreadyDeleted": true to the same document.
mocactl spawn creates a session (pinned to the bundle if --config is given), writes a record
to $XDG_STATE_HOME/mocactl/subagents.jsonl, then forks a detached worker that holds the sync
POST /v1/runs call outside this process group. Quitting mocactl does not kill the worker; the
sessionId is printed on stdout immediately so a script can capture it. --kind solve requires
both --repo URL and --ref REF; --kind prompt refuses them. The optional --tag T groups
related spawns (e.g. a parent agent's own subagents under one tag) so mocactl subagents --tag T
can list them in isolation. The optional --label L names one dispatch within a tag group
(diagnose, fix, fix2): mocactl-local, surfaced on mocactl subagents as a LABEL
column (- on unlabeled rows) and on --json as label on rows that have one. Alphabet
is [A-Za-z0-9][A-Za-z0-9._-]{0,63} (stricter than --tag so jq-side filtering doesn't
need quoting).
mocactl spawn --prompt-file FILE reads the prompt from FILE (UTF-8, trimmed; must be a regular
file, no symlinks) instead of positional argv. Mutually exclusive with an inline prompt. Use it
when the prompt would carry characters a parent shell or coding agent refuses on argv
(multi-line, #, $(...), heredocs) — typically when chaining subagents. Same 64 KiB cap as
inline prompts.
mocactl subagents reads the ledger and joins it with /runs/status, resolving the server's
queued ambiguity with child-pid liveness and a 60-second grace: a queued row with a live
child is running; past the grace with a dead child it is unknown. Without --tag, every
spawn you own is listed, oldest first by dispatch time. A client-side fetch cutoff on the
worker after the request landed (undici's 5-min headersTimeout is the common one) is
reconciled on the next poll instead of reported as failed; a connect-phase failure
(ECONNREFUSED, DNS, TLS) is still terminal, since the server never saw the request.
mocactl watch is subagents as a stream: it sweeps the same rows the same way and prints one
line per state change, exiting 0 once every row it watches is finished — done, failed,
paused, or unknown for one that will never produce a result. The first sweep reports every
row, so watching a batch that is already over says so. It follows the owner-scoped event stream
GET /v1/events, so a transition shows up within about a second, and --since C resumes after a
cursor C (every --json line carries the one it came from). Behind the stream is a 60-second
read of every unfinished row, which is the whole answer for a row with no turn, a control plane
without the route, and an event the server lost. It re-reads the
ledger each sweep, so a spawn --tag T from another terminal joins a running watch --tag T:
spawn a few, watch, spawn more. One line per event is what a coding agent's background monitor
wants (Claude Code's Monitor tool, for one) — with --json each line is its own JSON object, so
nothing has to be parsed twice. Ctrl-C ends the watch; the subagents keep running.
mocactl get SESSIONID fetches a terminal result and writes files to --out DIR (default: cwd):
<sid>.text for a prompt response, <sid>.patch for a solve result (with a trailing newline
normalized so git apply does not reject it), and <sid>.verdict.json if the server returned a
verdict. A session that has not finished yet exits 1 with a hint; a failed body exits 1
with the status, reason, and detail on stderr.
mocactl run continues the session --session names, or starts a new one (--new, the default).
An empty --session "" is refused (exit 2), not taken as --new. When the harness has no
capacity (503 with Retry-After), it waits and retries, printing the harness's reason (for
example no attached sandbox in sandbox tier 'container'), for at most 15 minutes in all; then it
exits 1 with that refusal. A tier or template with no worker never gains one by waiting.
By default it prints the assistant's text only. --show-tools adds each tool call the turn makes,
on its own line between the text, formatted as the TUI formats it ($ ls /tmp, read src/a.ts),
and marks a tool call that failed; a successful call's output is not printed. It is refused with
--json, which already streams the tool_use and tool_result frames themselves.
mocactl promote prints what it built and the preflight report (warnings on stderr) BEFORE
uploading, then the bundle digest to pass to run --config. --dry-run builds and prints without
uploading, and needs no login. It exits 2 when refused before upload (a usage error, not logged
in, or preflight errors), 3 on a structural credential match, and 1 for anything else. In the
TUI, /promote DIR attaches it to the next session you create; its toast counts skills, commands
and warnings. With exactly one inference credential and no presets, the new-session overlay creates
the session as soon as it opens, so /promote DIR starts the session right away. A session's
bundle is fixed when it is created, so
--config cannot be combined with --session.
Stored bundles count against a per-account and a deployment-wide byte budget (429 when full).
mocactl bundles list prints the bundles you own — digest, the bytes each is charged, when it was
promoted and when it expires — newest first, so a digest you lost after promote is still
recoverable instead of holding your budget until it expires. It prints the digest in full because
that is what delete takes. BYTES is the charge, not the size of your directory: a small bundle
is still charged a 4 KiB minimum. A bundle promoted by the harness's own promote tool writes
Redis directly, keeps no budget entry, and so does not appear.
mocactl bundles delete DIGEST deletes a bundle you promoted and frees its share; an admin may
delete anyone's. Sessions created on it then fail their next turn as for an expired bundle.
mocactl promote DIR --dry-run prints a directory's digest without uploading. Rollout order: upgrade the harness before the
control plane — an older harness ignores configRef, so turns would run without the skills and
report no error.
mocactl credentials add reads the secret from stdin, never from the command line, so it stays
out of shell history and ps; it refuses a terminal on stdin (read -rs KEY first, or use
/credentials in the TUI). For a kind with one secret field (bearer, api-key,
oauth2-token) stdin is the secret itself, one line, its trailing newline dropped, with no
field= prefix and no surrounding whitespace; for any other kind it is one field=value per line
(basic, which is not for inference: --consumer sandbox-egress, then username=… and
password=…). --kind defaults to bearer and --consumer to inference, as in the TUI form;
--host takes a comma-separated list too and is required, and --endpoint is for inference
only. The TUI form's checks apply, all but the secret's before stdin is read, and a problem names
fields, never values. It says on stderr when it starts reading stdin.
Exit codes, for every command: 0 it worked, 1 it failed (the turn, or the control plane
refused), 2 a usage or setup problem (bad flags, not logged in, no destination for the turn),
130 cancelled (Ctrl-C, which also stops a listing or a stdin read that is waiting).
Delegate with context​
A workload gives a subagent files to work from: a context, uploaded once and available read-only
to every run on it (docs/harness/how-to/workloads.md). Build the context
file with contextctl (mocactl never calls it), then:
contextctl ctx pack ./repo -o ctx.context
id=$(mocactl workloads create --context ctx.context --name demo)
sid=$(mocactl spawn "summarize the repo in the context" --kind prompt --workload "$id")
mocactl get "$sid" # once `mocactl subagents` says done
mocactl workloads delete "$id"
ctx pack puts the directory's files under the bundle's workspace/ directory. It needs a Context
Service with rossoctl/context-service#56
(workspace bundles). A run starts in its context: the agent's working directory shows the bundle's
workspace/ directory (src/, not workspace/src/), or the whole bundle when it has no
workspace/ directory or has other content too. A read-only run gets the session's own working
directory (/workspace/<session> on container workers) as writable scratch space. See "Runs" in
docs/harness/how-to/workloads.md.
workloads create creates the workload (POST /workloads on the harness, with your API token),
uploads the file straight to Context Service with the one-time grant it returns, then activates the
revision the upload reports, which freezes it. It checks that the file exists before it starts, and
that it is no larger than the grant allows before it uploads; the upload streams from disk. A grant
that has expired, or that the upload refuses with 401, is replaced once
(POST /workloads/ID/uploads). The grant's URL must be HTTPS (plain HTTP only on loopback). If
anything fails after the workload exists, create deletes it again, so it does not count against
your quota (5 live workloads by default), and exits 1. --name is a lowercase Kubernetes name of
at most 50 characters; without one create generates one (wl- and 8 hex) before it sends the
request, so if the reply is lost (Ctrl-C, a dropped connection) it can still name the workload to
delete.
workloads list shows what you own, newest first, when you no longer have the id create printed
(GET /workloads, #552). It is the way out of a
workload holding a quota unit under a name nothing recorded:
mocactl workloads list
# WORKLOAD STATUS TYPE SIZE SANDBOXES CREATED REVISION
# wl-3f9c1a04 ready workspace 1Gi - 4m ago 8c1d0e4a2b77
# demo awaiting_upload workspace 1Gi - 2h ago -
mocactl workloads delete wl-3f9c1a04
Your own workloads only: there is no route that lists another user's, and none that lists everyone's.
A deleting workload is listed, because it still holds its quota unit and a repeated delete is
how to clear it; a deleted one is not, though workloads get still reads it for a day. The
listing never settles a provisioning workload, so SANDBOXES can lag — workloads get ID is
what settles one. CREATED is - for a workload created before the harness recorded the field;
those are also absent from the listing (see "Upgrading" in
docs/harness/how-to/workloads.md). With no workloads at all, it says
no workloads on stderr and prints no table, so mocactl workloads list | wc -l counts workloads;
--json prints {"workloads": []}.
--sandboxes N gives the workload N sandboxes of its own instead of the operator's shared pool
(phase 2, #476; "Own sandboxes" in
docs/harness/how-to/workloads.md). --mount read-only or
--mount writable, which needs --sandboxes, also gives it a volume of its own holding the
context, mounted into those sandboxes, so runs use it with no per-run copy; with writable, what
one run writes the next sees. The deployment must run moca-provisioner, or the harness refuses
sandboxes (400 workload_field_not_allowed). Activation answers provisioning while the
sandboxes start: create then polls GET /workloads/ID every 2 seconds, for up to 5 minutes,
until the workload is ready. On seed_bundle_missing (the provisioner lost the bundle, for
example after a restart) it activates once more. Any other error the harness records, the same
error twice, or the timeout is a failure (it deletes the workload, as for any other failure).
--sandboxes is a whole number of at
least 1 (the harness caps it, 2 by default); either flag outside workloads create exits 2.
spawn --workload ID adds workloadId to the run and records it in the ledger row
(mocactl subagents --json shows it as workload). Only prompt runs can use a workload, so
--workload needs --kind prompt. Before it creates the session, spawn checks the workload
(GET /workloads/ID) and exits 1 when it is missing, not yours, or not ready (naming its
status). A workload that stops being ready after that fails the run (workload_not_ready,
workload_not_found), as mocactl subagents then shows.
spawn --workload ID --writable gives the run its own writable copy of the context instead, for a
subagent that edits files or reruns tests. The copy is the run's working directory and is discarded
when the run ends, so ask the subagent to return its changes (a diff, test output) in its answer. It
sends contextWritable: true and records writable in the ledger row, which
mocactl subagents --json shows as "writable": true on that row only. --writable without
--workload exits 2.
Output​
stdout carries only the result; every message goes to stderr, including "no sessions" for an
empty list. Without --json a listing is an aligned table with a header row, made terminal-safe.
Times are UTC. With --json stdout is one JSON document and one line; run, doctor and watch
keep their own shapes (watch emits one object per line as events arrive). These shapes are
stable: fields may be added, but none is renamed or removed.
| Command | --json on stdout |
|---|---|
sessions | {"sessions":[{"sessionId","title","state","createdAt","lastTurnAt"}]} |
sessions delete | {"sessionId","status"}, status being deleted, or accepted while the control plane finishes |
credentials | {"credentials":[{"name","kind","consumer","hosts","endpoint"}]} |
credentials add | {"name","status":"stored"} |
credentials delete | {"name","status":"deleted"} |
spawn | {"type":"session","sessionId","pid"} |
subagents | {"subagents":[{"sessionId","tag","kind","state","detail","bundle","workload","submittedAt"}]} |
watch | NDJSON, one event per line: {"sessionId","tag","label"?,"kind","state","detail","at"} |
get | {"sessionId","status","files":["<path>",…],"reason"?,"message"?} |
workloads create | {"workloadId","status","contextType","revision","files","bytes","sandboxes"?,"mount"?} |
workloads list | {"workloads":[{"workloadId","status","contextType","workspace","createdAt","revision","sandboxes","error"?}]}, null unset, createdAt ISO 8601 |
workloads get | {"workloadId","status","contextType","workspace","revision","sandboxes","error"?}, null unset |
workloads delete | {"workloadId","status":"deleted","alreadyDeleted"?} |
createdAt and lastTurnAt are epoch milliseconds as the control plane sends them (lastTurnAt
is null before the first turn); endpoint is null when the deployment default applies.
title is this machine's: the first prompt, or a TUI rename, and null for a session with no
local history (the control plane stores no titles).
Sandboxes and templates​
mocactl sbx is the sandbox service's client: log in with mocactl sbx login, list templates with
mocactl sbx templates, and create a sandbox of one with mocactl sbx create --template ID (or
sbx up --template ID in a repository). On a deployment with the template store,
mocactl sbx templates also creates, follows, activates and retires your own templates. The
sandbox service user guide has every command; turning a container image into a
template is the template onboarding guide, deploy/sbx/template-onboarding/GUIDE.md.
Files​
$XDG_CONFIG_HOME/mocactl/config.json— endpoints, theme, toggles, keybinds, presets.$XDG_CONFIG_HOME/mocactl/auth.json— the 15-minute API token and the refresh token that renews it (mode 0600). A login renews itself for 30 days after its last use and 90 days at most; every renewal replaces the refresh token, so a copied file stops working the next time either copy is used.mocactl logoutends it. No provider key is ever stored.$XDG_STATE_HOME/mocactl/subagents.jsonl— ledger of subagents spawned on this machine (mode 0600). Append-only JSONL;mocactl subagentsreads from it. Includes the dispatch envelope so a future gate-decision command can resume the subagent. Compaction is not automatic yet; the file grows one line per spawn plus one per state transition.$XDG_STATE_HOME/mocactl/transcripts/— local session history, per subject and per control plane (mode 0600). A session resumed from another machine shows no history — it belongs to a different transcript store.
Falls back to ~/.config/mocactl/ and ~/.local/state/mocactl/ when the XDG_* variables are unset.
Troubleshooting​
Run mocactl doctor. Its "harness located" line says where the harness was found and how. If the
control plane advertises none, its operator sets SH_PUBLIC_HARNESS_URL to the harness as clients
reach it (not the in-cluster address; behind a port-forward, the local one), e.g.
kubectl set env deploy/sh-control-plane SH_PUBLIC_HARNESS_URL=http://localhost:18081. A control
plane older than /v1/discovery needs upgrading, or --harness-url in the meantime.
If it reports that the harness does not trust this control plane, the harness is missing the
control plane's public keyset, the exchange token, or SH_CONTROL_PLANE_URL/SH_REQUIRE_AUTH. On
the VM/P6 path, re-run sudo ./deploy/vm/setup-vm.sh, which installs the control plane beside the
supervisor and wires all four (Single VM, "The control plane"). There the exchange token
is a systemd credential, not a supervisor.env line.
Resuming a session started on another machine shows no history: the control plane has no route that returns a session's messages yet, so history is kept locally.
Creating a credential requires at least one destination host — the control plane rejects an empty list.