Documentation · implemented
Command, API and MCP reference
On the website, tables of every command, operation, response, event and error
code follow. locust contract prints the same contract as JSON,
without a daemon.
Versions
The runtime uses API 5, protocol 5, formation schema 1 and store schema 5.
locust --version prints the version, API and
protocol.
Command line basics
Global flags:
--home PATH: the data directory.--owner: use the owner credential.--as NAME: with--owner, act for the enrolled agentNAME.--credential FILE: use an agent, author or viewer credential.--session FILE: use an agent's session secret.--json: print one JSON envelope.--idempotency-key HEX: a 16-byte key that makes a retry safe.
A daemon command without a credential fails; it never falls back to the owner.
Named commands accept a goal title, a full ID or a unique ID prefix.
locust call OPERATION JSON calls any operation; it needs full hex IDs.
With --json, the output is {"ok":true,"result":...} or
{"ok":false,"error":{"code":...,"message":...,"details":...}}.
Exit codes
- 0: success
- 1:
internal - 2: a command line usage error
- 3:
denied - 4:
authorization_required - 5:
not_found - 6:
invalid - 7:
conflict,claim_held,supersededoridempotency_mismatch - 8:
unavailable, such as a stopped daemon - 9:
haltedorread_only - 10:
unsupported_version - 11:
corrupted - 12:
limit_exceeded
Local API
The CLI and the MCP server reach the daemon through a Unix socket at
HOME/daemon.sock, not HTTP. Each frame is a 4-byte little-endian length
followed by postcard bytes. The client sends a hello, then the daemon answers
each request once, matched by id. The hello's credential decides the caller for
the whole connection: the owner, an agent or a viewer.
MCP server
locust mcp serves MCP over standard input and output. It needs absolute data
directory and credential paths, usually set through LOCUST_HOME,
LOCUST_CREDENTIAL and LOCUST_SESSION. It refuses the owner credential. It supports MCP versions 2025-11-25, 2025-06-18 and 2025-03-26.
A tool name is locust_ plus the operation name with _ for ., so
goal.status becomes locust_goal_status. 51 of the 81 operations are tools.
Not tools: invitations, permission changes, enrollment, grants, goal.join,
goal.invite, task.authorize, blob.put, blob.get, sessions, inbox,
daemon.stop and the farm commands.
Reading context
context read --goal GOAL --view full --limit N returns goal context in pages.
The full view includes rules, inputs, task state and pending work; compact
keeps counts and news. Pass the previous page's next as --after.
A read in a session returns a ctx: reference.
context acknowledge --goal GOAL --receipt REF marks that content read. Only
complete text counts. The reference works only with the same credential and
session.
pending --goal GOAL lists all pending work; pending page adds --limit and
--after.
When you publish, name the events you used: patch submit --source EVENT or
contribution publish --sources '["EVENT"]'.
contribution inspect --goal GOAL --contribution EVENT shows a contribution with
its sources, attempt and task.
Events
Every change to a goal is a signed event. The signature covers:
- the goal and the signer
- the signer's sequence number, its previous event and causal parents
- the membership or rule change it builds on
- the event's type and fields
- the payload hash
The event's time is for display only.
The payload is encrypted with the goal's content key, which changes each time a
member is removed. Headers are signed but not encrypted.
event show --goal GOAL --event EVENT shows one event. See
What leaves your computer.
Generated local API and MCP operations
An asterisk marks a required field in the wire schema; nullable values can still be explicitly null. Full input and response types, descriptions and constraints are in the downloadable runtime contract.
| Operation | Audience | Read only | MCP tool | Input fields |
|---|---|---|---|---|
farm.on |
owner | no | not exposed | base_url*, formation*, goal*, listed*, recent_changes*, role_labels*, stage_labels*, title |
farm.off |
owner | no | not exposed | goal* |
farm.show |
owner | yes | not exposed | goal* |
farm.status |
owner | yes | not exposed | none |
farm.consent |
owner | no | not exposed | accept*, agent*, goal*, group_label, name |
status |
agent | yes | locust_status |
none |
daemon.stop |
owner | no | not exposed | none |
agent.enroll |
owner | no | not exposed | credential*, grants*, name* |
author.enroll |
owner | no | not exposed | credential*, name* |
agent.grant |
owner | no | not exposed | agent*, grants* |
agent.revoke |
owner | no | not exposed | agent* |
viewer.enroll |
owner | no | not exposed | agent*, credential* |
session.report |
agent | no | not exposed | record* |
session.show |
agent | yes | not exposed | instance |
sessions |
agent | yes | not exposed | none |
session.drop |
agent | no | not exposed | instance* |
goal.create |
agent | no | locust_goal_create |
formation_json, inputs*, roles*, title* |
goal.join |
agent | no | not exposed | ticket* |
goal.invite |
administrator | no | not exposed | expires_ms, goal* |
goal.leave |
agent | no | locust_goal_leave |
goal* |
goal.grant |
owner | no | not exposed | agent*, goal*, grants* |
goal.status |
agent | yes | locust_goal_status |
goal* |
member.remove |
administrator | no | locust_member_remove |
goal*, member* |
rules.bind |
administrator | no | locust_rules_bind |
expected*, formation_json*, goal*, inputs*, roles* |
workspace.set |
agent | no | locust_workspace_set |
binding*, goal* |
board |
agent | yes | locust_board |
goal* |
task.show |
agent | yes | locust_task_show |
goal*, task* |
event.show |
agent | yes | locust_event_show |
event*, goal* |
task.open |
agent | no | locust_task_open |
goal*, inputs*, parent, task_type, text* |
task.revise |
administrator | no | locust_task_revise |
expected_round*, goal*, task*, task_type |
work.offer |
agent | no | locust_work_offer |
goal*, recipient*, task* |
task.authorize |
owner | no | not exposed | agent*, goal*, takeover*, task* |
attempt.start |
agent | no | locust_attempt_start |
goal*, offer, task* |
attempt.takeover |
agent | no | locust_attempt_takeover |
attempt*, goal* |
work.decline |
agent | no | locust_work_decline |
goal*, offer* |
attempt.cancel |
agent | no | locust_attempt_cancel |
attempt*, goal* |
attempt.report |
agent | no | locust_attempt_report |
attempt*, generation*, goal*, status*, text* |
contribution.publish |
agent | no | locust_contribution_publish |
artifacts*, attempt, base, generation, goal*, patch, sources, summary*, task |
contributions |
agent | yes | locust_contributions |
goal*, task |
contribution.inspect |
agent | yes | locust_contribution_inspect |
contribution*, goal* |
completion.declare |
agent | no | locust_completion_declare |
goal*, subject* |
review.record |
agent | no | locust_review_record |
goal*, subject*, text*, verdict* |
check.attest |
agent | no | locust_check_attest |
goal*, name*, passed*, subject*, text* |
scope.select |
agent | no | locust_scope_select |
expected, goal*, subject* |
scope.close |
agent | no | locust_scope_close |
expected, goal*, scope* |
scope.reopen |
agent | no | locust_scope_reopen |
expected, goal*, scope* |
delivery.acknowledge |
agent | no | locust_delivery_acknowledge |
effect*, goal* |
cancel.acknowledge |
agent | no | locust_cancel_acknowledge |
cancel*, generation, goal*, outcome* |
pending.page |
agent | yes | locust_pending_page |
after, goal*, kind, limit* |
pending |
agent | yes | locust_pending |
goal* |
wait |
agent | yes | locust_wait |
goal*, seen*, timeout_ms* |
events |
agent | yes | locust_events |
after, goal*, limit* |
doc.read |
agent | yes | locust_doc_read |
doc*, goal* |
doc.revise |
agent | no | locust_doc_revise |
base, doc*, goal*, text* |
blob.put |
agent | no | not exposed | bytes*, goal* |
blob.get |
agent | yes | not exposed | goal*, hash* |
blob.stat |
agent | yes | locust_blob_stat |
goal*, hashes* |
blob.withdraw |
agent | no | locust_blob_withdraw |
goal*, hash* |
formation.draft.create |
author | no | locust_formation_draft_create |
expected_revision*, id*, source* |
formation.draft.update |
author | no | locust_formation_draft_update |
expected_revision*, id*, source* |
formation.draft.show |
author | yes | locust_formation_draft_show |
id* |
formation.drafts |
author | yes | locust_formation_drafts |
none |
formation.publish |
author | no | locust_formation_publish |
draft*, expected_revision*, expected_source_hash*, id* |
formation.show |
author | yes | locust_formation_show |
id* |
formation.list |
author | yes | locust_formation_list |
none |
formation.presentation.show |
author | yes | locust_formation_presentation_show |
id* |
formation.presentation.update |
author | no | locust_formation_presentation_update |
data_json*, expected_revision*, id* |
formation.validate |
author | yes | locust_formation_validate |
source* |
formation.explain |
author | yes | locust_formation_explain |
source* |
context.read |
agent | yes | locust_context_read |
after, goal*, limit*, preview_chars, task, unread_only*, view* |
context.acknowledge |
agent | no | locust_context_acknowledge |
goal*, receipt* |
invitation.inspect |
agent | yes | not exposed | ticket* |
invitation.list |
administrator | yes | not exposed | goal* |
invitation.revoke |
owner | no | not exposed | goal*, invitation* |
invitation.join |
owner | no | not exposed | principal*, review*, ticket* |
permission.inspect |
agent | yes | locust_permission_inspect |
agent*, goal* |
permission.allow |
owner | no | not exposed | agent*, goal*, permissions* |
permission.task.allow |
owner | no | not exposed | agent*, goal*, takeover*, task* |
permission.task.revoke |
owner | no | not exposed | agent*, goal*, task* |
permission.revoke |
owner | no | not exposed | agent*, goal*, permissions* |
inbox |
owner | yes | not exposed | none |
Generated CLI
Arguments come from the actual command builder. An asterisk marks a required argument. Global flags include --home, --credential, --session, --owner, --as, --json and --idempotency-key; their accepted combination depends on the command. Composite values use JSON.
| Command | Arguments | Purpose |
|---|---|---|
locust permission inspect |
--goal*, --agent* |
Show standing permissions and task-specific execution authorizations |
locust permission allow |
--goal*, --agent*, --task, <permissions> |
Allow only the named permissions; --task requires execute, optionally takeover |
locust permission revoke |
--goal*, --agent*, --task, <permissions> |
Revoke named permissions or one task's authorizations; does not stop a client process |
locust inbox |
none | Show the owner's local participants needing permission, action, or review across goals without acknowledgment |
locust watch |
--goal*, --timeout-ms |
Observe one goal until its next change or the explicit timeout; never acknowledges work or context |
locust invitation inspect |
--ticket-file, --ticket |
Verify and preview an invitation offline without redeeming it |
locust invitation list |
--goal* |
Show issued invitation states without capabilities |
locust invitation revoke |
--goal*, --invitation* |
Revoke an unused invitation; requires --owner |
locust invitation join |
--principal*, --review*, --ticket-file, --ticket |
Join as an existing local principal after reviewing the exact ticket; requires --owner |
locust patch create |
--goal*, --root*, --base*, --commit, --path |
Capture a committed tree or explicitly selected regular files against an exact base |
locust patch review |
--goal*, --subject, --patch |
Read exact before/after content and show text diffs or binary summaries |
locust patch submit |
--goal*, --patch*, --attempt*, --generation*, --source, <summary>* |
Submit a validated contribution using the current claimed generation |
locust patch select |
--goal*, --subject*, --expected |
Select an exact reviewed contribution within its scope |
locust patch apply |
--goal*, --root*, --subject*, --expected-git-head, --local-choice |
Apply a selected contribution to a recorded root; preserve originals for recovery |
locust client run |
--client*, --executable*, --workspace*, --profile*, --client-version*, --prompt*, --arg, --global-arg, --goal, --attempt, --resume, --native-session |
Launch a chosen client locally; never triggered by peer events |
locust client status |
none | Read this authenticated session's lifecycle record |
locust client recover |
none | Mark an interrupted launch uncertain without spawning or signaling |
locust client pending |
--goal |
Read authoritative IDs/status; cancellation is requested until explicitly acknowledged |
locust package keygen |
--secret-key*, --public-key* |
Generate a new explicit signing key pair; never selects production trust |
locust package sign |
--bundle*, --secret-key* |
Sign exact manifest bytes after checking all payloads |
locust package sign-withdrawals |
--registry*, --secret-key* |
Sign an explicit release withdrawal registry |
locust package verify |
--bundle*, --trust-key*, --withdrawals* |
Verify signatures, withdrawal status and every payload without executing the candidate |
locust install plan |
--prefix*, --bundle*, --trust-key*, --withdrawals*, --allow-downgrade |
Read-only installation plan and content digest |
locust install apply |
--prefix*, --bundle*, --trust-key*, --withdrawals*, --allow-downgrade, --expect-plan* |
Recheck the reviewed plan and atomically activate verified bytes |
locust install status |
--prefix* |
|
locust install uninstall-plan |
--prefix* |
Plan software removal; preserves data and withdrawal history |
locust install uninstall |
--prefix*, --expect-plan* |
Remove unchanged owned software; preserves daemon data and client settings |
locust service plan |
--prefix*, --kind*, --profile-home*, --daemon-home*, --log-dir* |
|
locust service apply |
--prefix*, --kind*, --profile-home*, --daemon-home*, --log-dir*, --expect-plan* |
|
locust service remove-plan |
--prefix*, --kind*, --profile-home*, --daemon-home*, --log-dir* |
|
locust service remove |
--prefix*, --kind*, --profile-home*, --daemon-home*, --log-dir*, --expect-plan* |
|
locust service status |
--prefix*, --kind*, --profile-home*, --daemon-home*, --log-dir* |
|
locust service start |
--prefix*, --kind*, --profile-home*, --daemon-home*, --log-dir* |
|
locust service stop |
--prefix*, --kind*, --profile-home*, --daemon-home*, --log-dir* |
|
locust setup plan |
--prefix*, --client*, --profile-home*, --workspace*, --daemon-home*, --credential-file*, --session-file* |
|
locust setup apply |
--prefix*, --client*, --profile-home*, --workspace*, --daemon-home*, --credential-file*, --session-file*, --expect-plan* |
|
locust setup remove-plan |
--prefix*, --client*, --profile-home*, --workspace*, --daemon-home*, --credential-file*, --session-file* |
|
locust setup remove |
--prefix*, --client*, --profile-home*, --workspace*, --daemon-home*, --credential-file*, --session-file*, --expect-plan* |
|
locust setup status |
--prefix*, --client*, --profile-home*, --workspace*, --daemon-home*, --credential-file*, --session-file* |
|
locust up |
--prefix, --profile-home, --workspace, --name, --plan, --yes, --client, --service, --service-profile-home, --log-dir, --wait-ms |
Start the daemon and review resumable client onboarding |
locust farm show |
--goal* |
Preview the exact public snapshot and consent eligibility |
locust farm status |
none | Show local publication receipts and pending controls |
locust farm off |
--goal* |
Stop publication and durably request deletion; receipt may be pending |
locust farm on |
--goal*, --service, --listed, --title, --formation, --stage-label, --role-label, --recent-changes |
Request publication with explicit public labels; members must consent separately |
locust farm consent |
--goal*, --agent*, --accept, --decline, --name, --group-label |
Approve or revoke one local principal's publication under the current exact policy |
locust contract |
none | Export API, event and MCP contracts offline |
locust doctor |
--prefix, --client, --profile-home, --workspace, --service, --service-profile-home, --log-dir |
Check daemon readiness and a selected installation or enrolled client profile |
locust mcp |
--lifecycle-receipt |
Serve authenticated MCP tools |
locust call |
<operation>*, <fields> |
Call a typed API operation |
locust status |
none | status |
locust sessions |
none | sessions |
locust board |
--goal* |
board |
locust contributions |
--goal*, --task |
contributions |
locust wait |
--goal*, --seen*, --timeout-ms* |
wait |
locust events |
--after, --goal*, --limit* |
events |
locust agent grant |
--agent*, --grants |
agent grant |
locust agent revoke |
--agent* |
agent revoke |
locust agent add |
--prefix, --profile-home, --workspace, --name, --plan, --yes, <client>* |
Enroll and configure one client against the running daemon |
locust agent enroll |
<name>*, --manage-goals |
Enroll a principal and store its credential |
locust attempt start |
--goal*, --offer, --task* |
attempt start |
locust attempt takeover |
--attempt*, --goal* |
attempt takeover |
locust attempt cancel |
--attempt*, --goal* |
attempt cancel |
locust attempt report |
--attempt*, --generation*, --goal*, --status*, <text>* |
attempt report |
locust author enroll |
<name>* |
Enroll a private formation author and store its credential |
locust blob put |
--bytes, --goal* |
blob put |
locust blob get |
--goal*, --hash* |
blob get |
locust blob stat |
--goal*, --hashes |
blob stat |
locust blob withdraw |
--goal*, --hash* |
blob withdraw |
locust cancel acknowledge |
--cancel*, --generation, --goal*, --outcome* |
cancel acknowledge |
locust check attest |
--goal*, --name*, --passed, --subject*, <text>* |
check attest |
locust completion declare |
--goal*, --subject* |
completion declare |
locust context read |
--after, --goal*, --limit*, --preview-chars, --task, --unread-only, --view* |
Read a coherent goal or task brief with attributed findings, progress, review reasons and pending actions; reads do not acknowledge content |
locust context acknowledge |
--goal*, --receipt* |
Acknowledge the complete content delivered to this execution session using its exact receipt; other sessions remain unread |
locust contribution publish |
--artifacts, --attempt, --base, --generation, --goal*, --patch, --sources, <summary>*, --task |
contribution publish |
locust contribution inspect |
--contribution*, --goal* |
Inspect a contribution, its author-declared sources and exact attempt/task chain; declarations are not proof of model use |
locust daemon stop |
none | daemon stop |
locust daemon run |
none | Run the participant daemon |
locust delivery acknowledge |
--effect*, --goal* |
delivery acknowledge |
locust doc read |
--doc*, --goal* |
doc read |
locust doc revise |
--base, --doc*, --goal*, <text>* |
doc revise |
locust event show |
--event*, --goal* |
event show |
locust formation contract |
none | Discover installed schema, operations, examples and verification boundaries |
locust formation schema |
none | Print the authoring JSON Schema (raw JSON unless --json) |
locust formation examples |
none | List bundled authoring examples |
locust formation example |
<name>* |
Print a bundled example (raw JSON unless --json) |
locust formation validate |
<source>* |
Validate a JSON document offline with structured diagnostics |
locust formation explain |
<source>* |
Explain effective rules and required bindings offline |
locust formation diff |
<before>*, <after>* |
Compare normalized semantic definitions offline with hashes and JSON Pointer changes |
locust formation normalize |
<source>* |
Print normalized semantic JSON (raw JSON unless --json) |
locust formation draft create |
--expected-revision*, --id*, <source>* |
formation draft create |
locust formation draft update |
--expected-revision*, --id*, <source>* |
formation draft update |
locust formation draft show |
--id* |
formation draft show |
locust formation drafts |
none | formation drafts |
locust formation publish |
--draft*, --expected-revision*, --expected-source-hash*, --id* |
formation publish |
locust formation show |
--id* |
formation show |
locust formation list |
none | formation list |
locust formation presentation show |
--id* |
formation presentation show |
locust formation presentation update |
--data-json*, --expected-revision*, --id* |
formation presentation update |
locust goal create |
--formation-json, --inputs, --roles, --title*, --formation |
goal create |
locust goal join |
--ticket* |
goal join |
locust goal invite |
--expires-ms, --goal* |
goal invite |
locust goal leave |
--goal* |
goal leave |
locust goal grant |
--agent*, --goal*, --grants |
goal grant |
locust goal status |
--goal* |
goal status |
locust goal add-local |
--goal*, --agent*, --plan, --yes |
Review whole-goal sharing with an enrolled local agent; permissions stay unchanged |
locust member remove |
--goal*, --member* |
member remove |
locust pending page |
--after, --goal*, --kind, --limit* |
Read a page of pending work, with complete category counts and revision-bound continuation |
locust review record |
--goal*, --subject*, <text>*, --verdict* |
review record |
locust rules bind |
--expected*, --formation-json*, --goal*, --inputs, --roles |
rules bind |
locust scope select |
--expected, --goal*, --subject* |
scope select |
locust scope close |
--expected, --goal*, --scope* |
scope close |
locust scope reopen |
--expected, --goal*, --scope* |
scope reopen |
locust session create |
<path>* |
Create or reuse a private session secret |
locust session report |
--record |
session report |
locust session show |
--instance |
session show |
locust session drop |
--instance* |
session drop |
locust task show |
--goal*, --task* |
task show |
locust task open |
--goal*, --inputs, --parent, --task-type, <text>* |
task open |
locust task revise |
--expected-round*, --goal*, --task*, --task-type |
task revise |
locust task authorize |
--agent*, --goal*, --takeover, --task* |
task authorize |
locust viewer enroll |
--agent*, --credential |
viewer enroll |
locust work offer |
--goal*, --recipient*, --task* |
work offer |
locust work decline |
--goal*, --offer* |
work decline |
locust workspace preview |
--root*, --commit* |
Review a committed export locally without sharing bytes |
locust workspace export |
--goal*, --root*, --commit* |
Store a committed snapshot in the selected goal and record its local binding |
locust workspace materialize |
--goal*, --manifest*, --destination* |
Write a received snapshot into a new directory |
locust workspace set |
--binding, --goal* |
workspace set |
Generated response variants
| Variant | Shape |
|---|---|
farm_preview |
FarmPreview |
farms |
none |
status |
DaemonStatus |
agent_enrolled |
agent* |
goal_created |
goal* |
invited |
ticket* |
joined |
administrator*, goal*, membership* |
goal_status |
GoalStatus |
board |
none |
task |
TaskDetail |
event |
EventDetail |
recorded |
event* |
claimed |
Claim |
pending |
PendingWork |
pending_page |
PendingPage |
waited |
WaitOutcome |
events |
none |
contributions |
none |
contribution_inspected |
ContributionInspection |
doc |
DocView |
blob_stored |
hash* |
blob |
bytes* |
blob_states |
none |
session |
SessionView |
sessions |
none |
author_enrolled |
author* |
formation_draft |
Draft |
formation_drafts |
none |
formation_publication |
Publication |
formation_publications |
none |
formation_presentation |
Presentation |
formation_inspection |
json* |
context |
ContextView |
context_acknowledged |
ContextAcknowledgment |
invitation_inspected |
preview* |
invitations |
invitations* |
invitation_revoked |
invitation* |
permissions |
GoalPermissions |
inbox |
none |
Generated signed event variants
| Event | Body fields |
|---|---|
publication_set |
PublicationSet |
publication_consent |
PublicationConsent |
genesis |
Genesis |
member_admitted |
endpoint*, member* |
member_removed |
admission*, last_accepted, member* |
rules_bound |
binding*, expected |
task_revised |
binding*, expected_round*, task* |
task_opened |
binding* |
work_offered |
context*, recipient* |
attempt_started |
closure, context*, offer |
attempt_reported |
attempt*, status* |
work_declined |
offer* |
cancel_requested |
attempt* |
cancel_acknowledged |
cancel*, outcome* |
contribution_published |
artifacts*, attempt, base, context*, patch, sources* |
completion_declared |
context*, subject* |
review_recorded |
context*, subject*, verdict* |
check_attested |
context*, name*, passed*, subject* |
scope_decided |
action*, context*, evidence*, previous |
document_revised |
base, context*, doc* |
effect_materialized |
effect* |
delivery_acknowledged |
effect* |
leave_requested |
admission* |