Server Overview
What the Waypoint server does and when you need it.
What it is
The Waypoint server is a Next.js application that stores sessions in a Postgres database and exposes them via a REST API. It's the central hub for team context — every developer's sessions flow in, and every agent queries out.
A server is required. If no server is configured, waypoint generate exits with a warning and the session is not saved. The server provides:
- Shared context — your agent benefits from sessions run by teammates
- Persistence — session history survives if a developer's machine dies or they leave the team
- Visibility — a web UI for browsing sessions, managing access, and auditing agent behaviour
Architecture
Developer A (any agent) → waypoint generate → POST /api/sessions ──────────────┐ ▼Developer B (any agent) waypoint-server → waypoint generate → POST /api/sessions ──────── (Postgres) │Developer A (next session) │ → get_waypoint_context → GET /api/sessions/context ◄───┘The server is stateless between requests. All state lives in the Postgres database.
API keys and scopes
Access is controlled by API keys. Each key has one or more scopes:
| Scope | What it allows |
|---|---|
sessions:write | Post new sessions (used by the CLI Stop hook) |
sessions:read | Query session context (used by the MCP server) |
admin:* | All of the above plus key management |
The CLI needs a key with sessions:write and sessions:read. Admins use admin:* keys.
Web UI
The server includes a web UI at / for browsing recorded sessions. Access requires logging in with an API key.
The /admin page (requires admin:* scope) lets you create and revoke API keys, and includes a danger zone for bulk operations.
Next steps
- Deployment — run the server with Docker or on a cloud platform
- Admin & Security — bootstrap, key rotation, recovery, and reset options
- Enterprise Self-Hosting — deploy on your own infrastructure