Quickstart

You'll have a working agent run in about five minutes. By the end of this page you'll have:

Signed in to the Catentio portal with your Huudis identity.
Invoked an agent and watched the run progress.
Inspected the run's cost, events, and output.

If you'd rather read about concepts first, jump to Concepts.

This quickstart uses the portal. If you would rather call Catentio from your own code, create an API key in the portal under API keys and use the public API instead:
curl -X POST https://catent.io/v1/runs \
  -H "Authorization: Bearer cat_pk_..." \
  -H "Content-Type: application/json" \
  -d '{"agent": "fumi", "message": {"content": "Write a headline for a cat sticker pack."}}'
Poll GET /v1/runs/{id} until status is succeeded, then read output.

Prerequisites

A Huudis account on the deployment's sign-in allow-list (HUUDIS_ALLOWED_USER_ID, or one of the ids in HUUDIS_ALLOWED_USER_IDS). Anyone else is rejected with 403 NOT_AUTHORIZED.
A browser.
About five minutes.

You do not need to configure tools, skills, or integrations to take an agent for a test drive. The runtime ships with defaults and the hachimi agent is callable out of the box.

Head to your Catentio portal — for the canonical instance, that's catent.io. Click Log in.

With email + password there's no visible redirect: the login form POSTs to the portal's own /api/v1/auth/login, which calls Huudis's token endpoint server-side, checks your identity against the sign-in allow-list, HMAC-signs a catentio_session cookie, and lands you on /dashboard.

With Google / Apple you do get redirected to Huudis and back to /callback, where the portal exchanges the one-time code and gates it the same way.

That cookie is the credential everything else runs on — the portal forwards it to the control plane as an x-catentio-session header on every call. See Authentication overview.

2. Invoke an agent

In the dashboard sidebar, click Agents. You'll see the roster — hachimi, tora, sai, ren, fumi, iro, and the rest. Click an agent (start with hachimi) to open its detail page.

Click Invoke, type a prompt, and submit:

Summarise the project board in three bullets.

Under the hood the portal POSTs to /api/v1/cp/v1/runs — the control plane's POST /v1/runs, through the portal's proxy:

{
  "agent": "hachimi",
  "transport": "rest",
  "prompt": "Summarise the project board in three bullets."
}

and gets back a run id:

{ "run_id": "gk3n7q2fzja4bdm6xr8v1cwt5p", "status": "queued" }

POST /v1/runs is the way to start a run, not POST /v1/agents/{slug}/invoke. The invoke route exists on the control plane but forwards to a runtime endpoint that doesn't exist, so it fails — see Agents → Not available. Run ids are 26-character base32 strings with no prefix.

3. Watch the run

The run shows up in Dashboard → Runs. Click into it and you'll see:

The agent's output, rendered as markdown, once the run finishes.
The event timeline — run_received, run_started, model_resolved, context_loaded, then claude_iteration / tool_call / tool_result repeating, ending in run_completed.
Dollar cost, summed from the run's events. Run costs are USD.
The model that actually ran, and which resolver rule picked it.
A context-window breakdown, if the run produced a session transcript.

The page polls for updates. There is no WebSocket and no SSE stream — nothing is pushed to your browser.

A run ends in one of: succeeded, failed, or cancelled. (The full status enum is queued, running, succeeded, failed, cancelled.)

Cost tracking is per-run, per-agent, per-model. For the workspace rollup, head to Dashboard → Cost, or read GET /v1/runs/costs, which breaks spend down by agent → tier → model over a 24h / 7d / 30d window.

4. Verify it worked

Back on Dashboard → Runs, your run's last event should be run_completed, and its output should be the agent's reply.

If the run detail panel says the run isn't found, that's expected for older runs: the agent's final output lives in the runtime's in-memory registry and ages out, while the event archive is durable. The run list and its event timeline are always there. See Runs → Two stores, two shapes.

You did it — you've completed your first Catentio agent run.

What's next