Skip to main content
The control plane is the FastAPI service that stores agent definitions and tokens and relays the serve/chat WebSockets. Prefer not to run it yourself? Use Hexgate Cloud — it’s the same service, hosted. Self-host when you need it inside your own infrastructure.

​
Run it

The default support-bot project is seeded on first boot with three agents — default (broad access, side-effects gated by approval_required), read_only (everything mutating denied), and support_bot (the role-aware demo that returns different answers per support / billing role).

​
Database — SQLite for dev, Postgres for production

make platform-api uses a local SQLite file — zero setup, ideal for dev and the test suite. For production, set DATABASE_URL to a Postgres DSN; bare postgres:// URLs are normalized to the asyncpg driver. A local Postgres is in the dev compose:
DATABASE_URL is read from the real environment or platform/api/.env. A managed Postgres (e.g. Scaleway, RDS) needs SSL in the DSN, e.g. …/hexgate?ssl=require. The SQLite DB lives at platform/api/hexgate.db; delete it and restart to wipe dev state.
Schema management. Tables are created with SQLAlchemy create_all; there is no migration runner, so a model change is applied by recreating the schema (make postgres-reset locally) rather than by an incremental migration. Plan schema upgrades as a maintenance step.

​
Endpoints

  • POST /v1/projects/:id/tokens — mint a dev token (returned in full once)
  • GET /v1/projects/:id/tokens — list dev tokens (masked)
  • DELETE /v1/projects/:id/tokens/:tid — revoke
  • GET /v1/projects/:id/agents — list agents with their YAMLs
  • GET /v1/projects/:id/agents/:name — read one agent
  • PUT /v1/projects/:id/agents/:name — save agent / policy / system YAMLs
  • POST /v1/agents — register a manifest (hexgate register / serve auto-register)
  • GET /v1/agents/:name — read an agent’s current policy (the hexgate serve fetch)
  • WS /v1/serve — producer socket (the hexgate serve CLI dials here)
  • WS /v1/projects/:id/chat — consumer socket (the dashboard Playground dials here)
The /v1/agents… and /v1/serve routes are not project-scoped in the path — the project is resolved from the bearer token (carried in the WebSocket subprotocol for serve), so a fty_live_… key both authenticates and selects the project. Only the dashboard-facing routes (/projects/:id/…, chat) take an explicit project id.

​
Health & readiness

GET /health is a dependency-free liveness probe. GET /ready reports downstream health — once ClickHouse is up it returns "clickhouse": "ok". See audit log for the audit store and email for outbound mail configuration.

​
Point the SDK at your instance

The key and URL are coupled: a fty_live_… key only verifies against the platform instance that minted it.