Skip to main content
Version: v0.11.0

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​

ActionSlashKeys
Command palette—ctrl+p
Sessions (resume, rename, delete)/sessions, /resumectrl+x l
New session/newctrl+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/credentialsctrl+x k
Toggle tool details / thinking/details, /thinkingctrl+x d, ctrl+x t
Copy last reply / export to Markdown/copy, /exportctrl+x y, ctrl+x x
Compose in $EDITOR/editorctrl+x e
Theme, diagnostics/theme, /doctor—
Help/help? on an empty input
Quit/quitctrl+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 watch and mocactl get are 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/reject for 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 polls every 5 seconds and re-reads the ledger each time, 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"}]}
watchNDJSON, 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 logout ends 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 subagents reads 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.