Developer overview
Everything in the console is a call to your gateway's REST v1 API. Nothing is hidden behind it, so anything you can click you can also script.
There are two surfaces, and they do different jobs:
| Surface | What it's for | Start here |
|---|---|---|
permaura | Running a gateway (permaura start) and controlling one from a shell | The permaura CLI |
| REST v1 | Integrating — anything you'd script, automate, or build on | REST API |
One binary does both. permaura start is the gateway; every other command talks to a gateway over REST v1, exactly as the console does. If you'd rather not install anything, npx -y permaura runs the same binary on demand.
The shape of it
Two protocols, two audiences:
- REST v1 is the operator plane — you, the console,
permaura, your scripts. It manages agents, connections, policies, grants, secrets, approvals, and the audit log. - MCP at
/mcpis the agent plane. Agents call capabilities; they cannot touch the operator plane. Tokens carry a role, and an agent token driving an operator endpoint is refused outright.
Where things live
| Binary | ~/.permaura/bin/permaura |
| Store (SQLite, includes the sealed vault) | ~/.permaura/gateway.db |
| Operator token | ~/.permaura/operator.token |
| Override the lot | PERMAURA_HOME |
What's not here yet
Being straight about the edges:
- There's no published OpenAPI document for REST v1. The route list on the REST API page is generated from the router by hand; the source of truth is the gateway itself.
- No client SDKs. REST v1 is plain JSON over HTTP with a bearer token;
curland your language's HTTP client are the whole story.
Contributing to these docs
Every page has an Edit this page link at the bottom that goes straight to its source in the docs repo. Corrections are welcome, especially where the product has moved and a page hasn't.