CLI and API reference

Draft for review

OrchKernel has two ways in besides the web workspace: the ok command line, and the HTTP API the workspace itself uses. This page lists both in one place. Each line points to the guide page that explains the command or route in full, so use it to find your way, then read the page it names.

The examples use the demo company from the Quickstart: ada the admin, maya the support lead, alice a sales rep, erin the engineering lead, pat the product lead, fiona the founder, and sam, tom and eli. Each person's sign-in token is printed when ok demo serve starts; those tokens are valid for 7 days.

The examples use 127.0.0.1:8080, the address ok demo serve listens on unless you pass --bind. Change the port if you started it elsewhere.

The command line#

Where a command works#

Most ok commands do not talk to a server. They open the state file (the SQLite file that holds the whole company; the demo's is orchkernel-demo/state.db), do their work and write the file back when they finish. A running server keeps the company in memory and writes the same file after each change, so it never sees what a command wrote, and its next write replaces it.

This holds even for commands that only read, such as ok log or ok inbox: they write the file back too.

To run a command on the demo, work in the folder where you ran ok demo (the one that holds orchkernel-demo):

1. Stop ok demo serve with Ctrl+C. The server writes the file after every change, so nothing is lost.
2. Run the command with the demo's state file and the person you act as: ok --state orchkernel-demo/state.db --as maya brain query tickets. You should see the demo's five support tickets as JSON, the first one T-1042, "Refund for a double charge on the September invoice".
3. Start the demo again with ok demo serve. It prints new sign-in tokens and revokes the ones it printed last time. Tokens you issued yourself keep working.

In the demo, ok --state orchkernel-demo/state.db --as ada kill actor:eli run with the server stopped printed "actor:eli engaged", and once the server started, GET /api/policy showed the switch on Eli held by an admin. The same command for Tom run while the server was up also printed "actor:tom engaged" and wrote a kill_switch event to the log, but the server never applied it, and its next write removed it from the file. The event stays in the log, so the log records a switch that never took effect. See Known problems.

Global flags#

Every command takes these, except -V, which only ok itself takes.

Two things catch people out:

• Without --state, a command in a folder with no .orchkernel/state.db creates a new, empty company there and works on that, with no warning.
• An --as that names nobody is refused by commands that check what you may do, such as ok brain query and ok kill ("Error: unknown actor nobody"). Others do not check: ok inbox, ok tasks and ok threads print nothing and succeed, and ok log prints the log. Without --as, the command acts as your computer login name, which the demo does not know either.

Environment variables#

The settings a server reads are listed in full in Self-hosting. These are the ones the command line itself reads.

Commands#

One line per command; run it with --help for its flags. The last column is the page that explains it.

Getting started and running

Company, people and tokens

Agents and work

Data

Governance and audit

Modules, connections and outside agents

Several organizations on one host

The HTTP API#

This part is for people writing scripts or tools against a running server. Everything the web workspace does, it does through this API.

Base path#

Every route is under /api on the server's own address, for example http://127.0.0.1:8080/api/me. Two exceptions sit at the root: the MCP endpoint POST /mcp for outside agents, and the operator API on its own listener when the server hosts several organizations. Any other path that is not under /api serves the web workspace. An /api path no route serves answers 404 not_found, "no such API route".

Bodies are JSON and need content-type: application/json. GET /api/health needs no token and answers { "ok": true, "dev_auth": false }.

Tokens#

Send a token in every request: Authorization: Bearer <token>. There are no passwords and no cookies.

To get a token for a script from the workspace (alice, in the demo):

1. Sign in as Alice and open your profile: choose your name, Alice Chen, at the bottom of the sidebar. On a phone, open the menu (the button at the top left) first. The page is titled Profile.
2. Under Sessions & tokens, choose New token.
3. In New sign-in token, type a Label ("Report script"), pick Valid for (1 day, 7 days, 30 days or 90 days; 30 days is preselected), then choose Issue token. The sheet Your new token shows it once, under "Copy it now: it is shown once. It expires ..." with a Copy button.
4. Choose I have copied it. The token now has its own row under Sessions & tokens, with its label, its dates and Revoke.
5. Try it: curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8080/api/me returns Alice's directory entry with "admin": false.

An admin issues tokens for others from People: each person has an Issue token button. Another person who tries over the API gets 403 "policy denied token.issue: only admins issue tokens for others". Tokens are valid 30 days unless you choose otherwise; the server keeps only a hash, so a lost token cannot be shown again. The full table of ways to issue and revoke is in Self-hosting.

Scopes. A token can be limited to some routes. The workspace cannot set scopes; use POST /api/tokens with "scopes", or ok token issue --scope with the server stopped. A scope can later be narrowed but never widened. On the profile page a scoped token's row says "limited to read" (or the scopes it has).

No scope reaches the audit routes. A route outside a token's scopes answers 403 token_scope, "this token's scopes do not reach /brain/collections/:name/query".

Failed tokens. A missing or bad token is 401. From the 61st failed credential in a minute, the address gets 429 rate_limited, "too many failed authentications from this address", with a Retry-After header for the rest of the minute. A valid token from the same address still works, and a request with no token at all is not counted and still gets 401.

Errors and status codes#

An error is JSON with a short code and a sentence:

{ "error": "denied", "message": "brain: access denied: ada may not read tickets" }

Some errors add a field: problems (a list of what is wrong) on 422 invalid, approval (its id) on 202 needs_approval, and evals (the case names) on evals_failing and evals_not_run.

Not every error has this shape. A body that is not JSON (400), a JSON body missing a required field (422), a missing content-type (415) and a wrong method (405) answer in plain text or with an empty body, for example "Failed to deserialize the JSON body into the target type: missing field goal". See Known problems.

The named codes each route can return are listed in the For developers section of the page that covers it.

Paging#

Long lists come a page at a time. Ask with ?limit= (default 200, at most 1000). When there is more, the answer carries an x-next-cursor header; send its value back as ?cursor= for the next page. The last page has no header.

1. curl -si -H "Authorization: Bearer $ADA" "http://127.0.0.1:8080/api/delegations?limit=2" returns two delegations and an x-next-cursor: MDky... header.
2. Repeat with &cursor=MDky.... You get the next two, and a new cursor.
3. Stop when a page comes back without the header.

A cursor stays valid when items are added or removed in between, with no repeats. Paged lists: /threads, /inbox, /approvals, /tasks, /runs, /traces, /knowledge, /decisions, /changes, /delegations, /views, /modules, /catalog, /connections and the gateway's action lists. /traces has its own limit (default 50, at most 200).

GET /events is not paged this way. It takes since (an event number) and limit, and without either returns the newest 200 events with last_seq, the newest event number in the log. The workspace polls /events?since=<last_seq> every two seconds.

Reads of a collection kept in another system can stop early (at 5,000 rows or after 60 seconds). The answer then carries x-ok-partial: true and names the vendor's adapter in x-ok-partial-from. GET /traces also sends x-ok-partial: true when it cut the archived runs short. The demo has no collection kept in another system, so this was not tried there. See Connections.

The live event stream#

GET /api/events/stream sends new events as server-sent events as they are written, only those you may see. Each message has the event number as id, the event type as event, and the event as JSON in data:

id: 422
event: knowledge_proposed
data: {"seq":422,"actor":"maya","event":{"type":"knowledge_proposed",...}}

• It starts at the newest event. Add since=<n> to start after event n.
• It takes the same filters as GET /events: type (comma-separated), run, thread, task, actor.
• A browser's EventSource cannot set headers, so this route alone also accepts the token as ?token=. On any other route a token in the address is ignored and the request gets 401.

To watch Maya's new knowledge entries: curl -N "http://127.0.0.1:8080/api/events/stream?token=$MAYA&type=knowledge_proposed", then add an entry as Maya. It arrives within a second.

When a connection drops, reconnect with since= set to the last id you received. The Last-Event-ID header a browser sends on reconnect is ignored, so events written while you were away are missed unless you pass since.

Route map#

All paths below are under /api. Each area's page has the bodies, answers and error codes in its For developers section.

POST /tick is for admins only; anyone else gets 403 "policy denied tick: admins only". POST /webhooks/:source takes a signature instead of a token (see Self-hosting); without a secret configured for the source it answers 401 "no webhook secret is configured for this source".

Known problems#

Found while writing this page; reported for fixing.

• Commands write over a running server, silently. Any state-file command run while the server is up, even a read such as ok log, writes the file back, and nothing stops or warns you. A change it makes (a kill switch, a token) is reported as done and logged, but the server never applies it and loses it at its next write. The log keeps the event anyway.
• A forgotten --state makes a new company. In a folder without .orchkernel/state.db, a command quietly creates an empty one.
• An unknown --as is not always caught. ok inbox, ok tasks and ok threads print nothing and exit 0, and an empty inbox or thread list prints nothing either, so the two look alike. ok log prints the whole log for an actor that does not exist.
• Some framework errors are not JSON. Malformed JSON, a missing field, a missing content-type and a wrong method answer in plain text or empty, not with error and message.
• Last-Event-ID is ignored on the event stream; pass since when you reconnect.
• Token kind has two shapes. POST /tokens answers "kind": "api"; GET /tokens lists "kind": {"type": "api"}.
• Help text. Many subcommands (ok runs, ok actor list, every ok brain subcommand, ok directory, ok schema, ok changes) show no description in --help, and some help lines cite internal design sections such as "(T§5)", "(SC§5.7)" or "(PC§7)".
• A demo that cannot start still prints tokens. When the port is taken, ok demo serve prints the tokens and "OrchKernel serving on ..." before it fails with "Address already in use", and the tokens it printed do not work against whatever holds the port.

Not possible yet#

• Running the state-file commands against a server: only ok policy, ok tenant and ok operator take --server.
• Issuing a scoped token from the workspace.
• Resuming the event stream from Last-Event-ID.
• A published OpenAPI description of the API. GET /api/schemas describes definitions (agents, skills, packs), not routes.