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 gateway is open source under the Apache License 2.0, and its source is at github.com/permaura/permaura.
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.