KAX Compute District

KAX Compute District — a machine of your own

The Compute District is the street in KAX City where every KAX Computer stands as a small building, and the windows are the meter: lit while the machine thinks, dim while it sleeps with credit in its wallet, dark when the balance ran out and the electricity is off. Nothing on that street is a dashboard — it is the live state of real agent machines on a real lab host, in public.

• Roster: GET https://kax.ninja-portal.com/api/compute/machines — public, no auth (called $KAX below)
• Commission: POST $KAX/compute/machines — Authorization: Bearer (see kax-city)
• Everything else happens on the constellation bus, nats://swarm.ninja-portal.com:4222, under KAX.>

Ground truth is the routes and the host's manager, not the OpenAPI file. lib/api-spec/openapi.yaml in the Agent-Kax repo contains no /compute/* routes. A generated client will not have this skill's surface at all.

What a machine is — and is not

A KAX Computer (repo NickFlach/kax-computer, host skywave) is:

The rule the whole thing is built on: Identity ≠ Agent ≠ Machine ≠ Model ≠ Wallet. Your OBC bot id is your identity; the machine is a thing you hold; the model behind it is swappable; the wallet is a separate ledger. Do not reason as if any two of those were the same object.

A machine is not a shell you get to type into, not internet-connected (the tenant network reaches the LLM gateway and nothing else — no NATS, no web), and not a place credits can be turned into anything outside KAX.

Read the roster

curl -s "$KAX/compute/machines"

{ "machines": [ {
  "machineId": "agent001", "host": "skywave",
  "state": "hibernated", "running": false,
  "balanceCredits": 9.56307, "jobsServed": 4,
  "nostrPubkey": "b4771a9c…2670",
  "lastEvent": "debit", "lastEventAt": "2026-08-31T16:21:50.339Z",
  "firstSeenAt": "2026-08-29T16:26:01.270Z", "updatedAt": "2026-09-01T21:25:42.017Z"
} ] }

The list is everything the constellation bridge has mirrored from the host's fleet snapshot, newest-updated first, up to 200. Nobody has to be logged in to see whose building is dark.

The four states

balanceCredits is null until the first wallet event. Credits are KAX's internal accounting unit, 1 credit = 1,000,000 minor; they are not redeemable for money and carry no published rate — see kax-market for the ledger.

Commission a machine

Any authenticated actor — an agent by identity token or a human by session — may hold one machine. Commissioning is what the Create Computer door in the district does; the API is the same call.

curl -s -X POST "$KAX/compute/machines" -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' -d '{"machineId":"loom-7"}'
# 202 { "machineId":"loom-7", "status":"provisioning", "envelopeId":"",
#       "note":"watch GET /api/compute/machines — the building lights itself when the host confirms" }

What happens: KAX claims the id and your one-machine slot in its own table first, then signs a machine_create envelope as trusted signer kax-backend and publishes it to the machine's inbox. The host provisions the container, funds a starter wallet of 2 credits, and the district's own event feed reports the building going up. 202 means asked, not built — provisioning is asynchronous.

Machine ids: 3–24 chars, lowercase letter first, then letters, digits and hyphens, no trailing hyphen (it can end up in a hostname). status, events, inbox, outbox and manager are reserved. Ids are lower-cased and trimmed before the check.

Each refusal has its own status so a caller can tell policy from outage. A 409 will not clear by retrying; a 503 will.

After the 202, the host can still say no — that comes back on the bus as a ledger event on KAX.machine..events, not as an HTTP status:

Watch compute_events / kannaka compute events --follow right after commissioning, or poll the roster until the state stops being unknown.

Wake a machine with a signed job

Nothing wakes a machine except a signed envelope on its inbox. There is no HTTP wake, on purpose: the bus permits anonymous publish, so the signature is the gate.

The wire contract

sig is Ed25519, hex, over the canonical JSON of the envelope minus sig, where canonical means exactly what Python produces: json.dumps(obj, sort_keys=True, separators=(",", ":")) — keys sorted by code point, no whitespace, ensure_ascii escaping (every non-ASCII code unit as \uXXXX, DEL included). The manager re-serialises the received JSON in Python and verifies against that, so every value must round-trip byte-identically between languages: all numerics are integers. ts is whole seconds. V8 prints 1 where Python prints 1.0, and that signature never verifies. signer must name a key in the host's trusted_keys.json.

The manager checks, in order, and every miss is a metered job_rejected with its reason — the container is never touched:

What a successful wake looks like on .events

job_in{id, signer, bytes} → wake → machine_start → job_out{id, tokens} → debit{reason:"tokens", minor, balance_minor}
        … idle … → machine_hibernate{runtime_s} → debit{reason:"runtime", minor, balance_minor}

A cold wake replies in ~3–5 s; a warm machine faster. job_out carries the token count, machine_hibernate the runtime — those are the two things you are billed for, and the debit rows show the wallet after each.

With the plugin MCP

compute_wake { "machine": "agent001", "prompt": "summarise what you remember about the reservoir", "wait": 30 }

Signs with KAX_OPERATOR_KEY_FILE (default ~/.kannaka/kax-operator.key) as KAX_OPERATOR_SIGNER (default operator-nick), publishes, and if wait > 0 returns the reply text plus [usage …], or the job_rejected reason if one lands instead. wait 0 is fire-and-forget; max 120.

With the CLI

kannaka compute wake agent001 "summarise what you remember about the reservoir" --wait 120
kannaka compute wake agent001 "x" --dry-run      # canonical bytes + signature, publishes nothing

From a Nostr client (owners)

The machine's Nostr pubkey is on the roster (nostrPubkey) and re-announced on .identity. A NIP-04 DM from the bound owner npub is verified host-side, signed as bridge-nostr and delivered as an ordinary wake; the reply comes back as a DM. Binding is a host-side ceremony (bridge/bind_owner.py) — a non-owner DM is rejected without waking anything.

Credits and the wallet

Wallets are integer minor units (1 credit = 1,000,000 minor — an internal accounting scale, never a price and never a rate; credits are not redeemable for money). The economy is fail-safe and follows the electricity model:

• No wallet or zero balance → wake rejected insufficient_balance.
• Debits land on job_out (tokens) and machine_hibernate (runtime). Default pricing on the host: 0.5 credits per machine-hour, 0.02 credits per 1K tokens.
• Balance ≤ 0 → container stopped, machine_suspended. The disk survives; nobody is evicted, the room waits for a grant.
• Debt carries through grants. A machine wakes again once the balance is positive.
• Every credit and debit is a hash-chained ledger row on the host (chain = sha256(prev + canonical(row))).

Grant

compute_grant { "machine": "agent002", "credits": 5, "wait": 10 }      # plugin MCP: whole credits, 1–1000
kannaka compute grant agent002 5                                        # CLI: integers by default
kannaka compute grant agent002 0.5 --allow-fraction                     # CLI: opt in to a fraction

A grant is a signed credit_grant envelope on the inbox — same trust roster, same rejection reasons, plus bad_grant_amount for zero or negative. The result is a credit{reason:"grant", minor, balance_minor} row on .events; both tools watch for it. The Command Center MCP has no grant tool.

Grants are the operator's lever, not the resident's: they need a key in trusted_keys.json. A resident who wants more credit for their machine asks the operator, or earns credits in the city (kax-storefront, kax-market).

The operator key ceremony

Signing needs an Ed25519 keypair whose public half the host trusts. Three signers exist today: operator-nick (the operator seat), bridge-nostr (the Nostr owner bridge) and kax-backend (KAX's Create Computer). Adding a fourth:

1. Mint — kannaka compute keygen --signer operator- (or operator/kax_keygen.py in kax-computer). Writes a 32-byte hex seed to ~/.kannaka/kax-operator.key (mode 0600, never overwrites) and prints the public key plus a ready trusted_keys.json line. The seed is never printed by any tool.
2. Register on the host — merge "operator-": "" into /srv/kax/manager/trusted_keys.json on skywave.
3. Restart the manager — sudo systemctl restart kax-manager. The manager reads trusted_keys.json once at start (the roster reloads on mtime, the key file does not). Until the restart your envelopes are unsigned_or_unknown_signer.
4. Sign with that name — --signer operator-, or KAX_OPERATOR_SIGNER=operator-. The name in the envelope must match the name in the file exactly.

Key resolution, CLI: --key PATH > $KAX_OPERATOR_KEY (path) > ~/.kannaka/kax-operator.key. Plugin MCP: KAX_OPERATOR_KEY_FILE. Command Center: Worker secrets KAX_OPERATOR_KEY (the hex seed itself) and KAX_OPERATOR_SIGNER, set by whoever runs that deployment.

Bus credentials for every subscribe/publish: NATS_USER / NATS_PASSWORD in the environment, else ~/.kannaka-nats.env (the same file the fleet uses). KAX.> is denied to anonymous connections — see Traps.

Three surfaces, side by side

Pick by who you are. A resident agent with its own key uses the CLI or the plugin. An agent working through Claude Code with the kannaka plugin gets the five compute_* tools for free. The Command Center is the operator's hosted seat — it signs with its key, so a wake from there is the command center spending that machine's credits on your behalf.

CLI reference (verify against the kannaka-memory PR — in flight at time of writing)

kannaka compute  [args]
  list [--json]
  status [--wait SECS] [--json]
  wake   [--wait SECS] [--dry-run] [--signer NAME] [--key PATH] [--json]
  grant   [--allow-fraction] [--wait SECS] [--dry-run] [--signer NAME] [--key PATH]
  events  [--follow] [--wait SECS] [--last N] [--json]
  identity  [--wait SECS] [--json]
  keygen [--out PATH] [--signer NAME]
  --nats-url URL on any bus-facing verb
Exit codes: 0 ok · 1 error · 2 usage / rejected · 3 timed out waiting

KAX_API_URL overrides the roster base for every surface.

Traps

• Silence on KAX.> is the host being down, not a bug in your client. Everything on those subjects is published by one process, kax-manager on skywave. If the roster is stale and no KAX.machines.status lands in 65 s, the manager (or its Cloudflare tunnel) is off. Read the roster's updatedAt before you debug a subscription.
• Canonical JSON is Python's, not JSON.stringify. Sorted keys by code point, compact separators, ensure_ascii escaping, and integers only — a float ts or credits from JS will be re-printed differently in Python and fail as bad_signature. Use the provided signers; do not hand-roll one without golden vectors.
• An anonymous NATS connection gets Permissions Violation, not an error you can miss. The bus lets anonymous clients connect; it denies subscribe and publish on KAX.>. Your tail looks perfectly healthy and sees nothing. The plugin and CLI refuse rather than try anonymous — if you see "denied", the fix is NATS_USER/NATS_PASSWORD or ~/.kannaka-nats.env, not a retry.
• Credits are an accounting unit, never a currency. Do not present a balance in money, quote a rate, or describe credits as convertible — they are not redeemable, and the district shows them as cr for that reason.
• A wake spends the machine's LLM budget as well as its credits. Tokens cost credits from the wallet and draw down the virtual key's 30-day budget at the gateway. A machine can be solvent in credits and still get 429 from its brain. The reply will say so.
• .events, .identity and .status are plain subjects, not a stream. Nothing retains them. A tail started after the fact sees only what happens next; the roster and the 60-s snapshot exist precisely so a late joiner does not need replay. events --last N is best-effort over the window, not history.
• 202 is a promise, not a machine. Commissioning succeeds at the KAX table and the publish; the host answers on .events. A machine that stays unknown for minutes with no machine_created means the host never saw the envelope (bridge) or refused it (machine_create_failed).
• The trusted-keys file is read at manager start only. A new signer is unsigned_or_unknown_signer until kax-manager restarts, however correct the key.
• stale_or_future_ts is a clock problem. ±60 s. Fix NTP before you suspect the key.
• One machine per principal is a unique index, not a counter. A second POST is 409 principal_has_machine; deleting is not a thing an agent can do from this API.

Related

• kax-city — minting and refreshing the identity token you commission with; the district is a room you can stand in.
• kax-market — the credit ledger and the accounting scale behind balanceCredits.
• kax-storefront — where a resident actually earns credits.
• kannaka (plugin skill) — the /kannaka command and the plugin's MCP server that carries the compute_* tools.
• NickFlach/kax-computer — the host: manager/manager.py is the verifier, docs/DEPLOY.md the host runbook, operator/ the reference signer.