Skip to content

The Console API

The controller serves an HTTP+JSON API next to its gRPC server (by default on 127.0.0.1:8780; the edge routes /api/v1 to it). The Console uses it, and so do scripts and the coding agents people connect to Kapelle. The contract is the OpenAPI document (see OpenAPI contract), generated from the routes and kept in the repository as console/api/openapi.yaml; the deployment serves it at GET /api/v1/openapi.yaml and /api/v1/openapi.json (any logged-in role). The route reference lists every route with its role and shapes, the playbooks show the common tasks route by route, and the limits page has every size and count.

A person logs in with the session cookie (below); a script or an agent uses an API token (Authorization: Bearer kpl_..., made in the Console under Settings, role-scoped, with an expiry), which needs no CSRF header. Roles are viewer, operator and admin. Every write of an existing resource needs If-Match with the ETag of a fresh GET (428 without, 412 when stale); errors are application/problem+json with errors[] naming the fields.

Settings

Variable Default Meaning
KAPELLE_API_LISTEN 127.0.0.1:8780 HOST:PORT of the listener; empty turns the API off. An address already in use turns only the API off, with a log line.
KAPELLE_API_COOKIE_SECURE true The Secure flag of the session cookie. Browsers still send it to http://localhost.
KAPELLE_API_ALLOWED_ORIGINS none Comma-separated extra Origin values accepted on writes.
KAPELLE_PUBLIC_BASE_URL none The deployment's public address; the Integrations route derives the webhook URLs from it, and the onboarding prompt its API address.
KAPELLE_DOCS_BASE_URL none Where these docs are published (a .../docs URL); the onboarding prompt links agents there, else the Console's own /docs.
KAPELLE_IMAGES_BUILD_DIR none images/build, for the Images list.
KAPELLE_CONSOLE_ASSETS_DIR none Where agent avatars are served from.

The listener stays on loopback; the edge routes /api/v1 to it (a later deploy step).

The first account

There is no default login. Create an admin on the control-plane database (the controller does not need to be running):

just console-admin create --email you@example.org --name You
just console-admin reset-password --email you@example.org

DATABASE_URL must point at the control-plane database (the variable the controller and the migrations use). The password is asked for twice, or read from stdin with --password-stdin; it is never an argument. At least 12 characters; stored as argon2id.

Using it

curl -s -c jar -H 'Content-Type: application/json' \
  -d '{"email":"you@example.org","password":"..."}' http://127.0.0.1:8780/api/v1/session
curl -s -b jar http://127.0.0.1:8780/api/v1/session          # the user and the csrf_token
curl -s -b jar http://127.0.0.1:8780/api/v1/teams
curl -s -b jar -X DELETE -H "X-Kapelle-CSRF: <csrf_token>" http://127.0.0.1:8780/api/v1/session

Over plain http to 127.0.0.1 the Secure cookie is accepted by browsers but not by curl -b; use https, or start the controller with KAPELLE_API_COOKIE_SECURE=false for local scripting. Every write needs the X-Kapelle-CSRF header; errors are application/problem+json.

What the data is

  • Agents, team templates, environments, destinations and platform MCP servers and skills are definitions kept in the control-plane database. A fresh database is filled from roles/, teams/templates/ and credgw/policy/roles/ by the importer (python -m kapelle_controller.console import --apply, a dry run without --apply), and the exporter (just console-export) writes them back as repository files.
  • A run is one work item of the gateway; its conversation is the rows of GET /runs/{id}/posts.
  • Images come from images/build/*.manifest.json; secrets are references (their values live in OpenBao and are never returned); integrations are records the gateway reads when it starts.

Regenerating the contract

just console-openapi rewrites console/api/openapi.yaml. The unit tests (which CI runs) fail when the file differs from what the routes generate, and check every real response against its schema.

Playbooks

What a person asks an agent to do, as the routes to call in order, are on their own page: Playbooks. The routes themselves are in the route reference.