API and realtime transport#

The Go backend serves the embedded SPA, JSON HTTP endpoints, tus uploads, and the application's WebSocket routes from one server.

Request path#

All /api/* and /ws* requests require a signed session for a registered user. They are also blocked until local-admin setup and at least one module declared as an access-gate provider is ready, except the module-driven agent-auth catalog, streams, and compatibility auth routes needed to finish onboarding.

Authentication routes#

Users and settings#

Agent authentication, capabilities, and skills#

The module descriptor chooses one auth mode: managed authorization code, managed device flow, managed API key, external, or none. Route registration follows the built auth binding, so a provider exposes only operations valid for its declared flow. MiniMax uses a write-only managed API-key binding whose status exposes only configured/unconfigured. Antigravity uses an external binding with no observable status, status stream, or managed host-login route; users authenticate it with agy inside each project.

GET /api/agent-auth is the frontend's authoritative auth registry. Each row contains provider, label, optional default, executionScopes, an authentication object (mode, optional instructions, and satisfiesAccessGate, and optional API-key creation metadata), and a normalized status object. Status contains authenticated, an optional warning, and one login shape shared by managed code/device flows (active, URL, optional code/timestamps/completion/error). Managed API-key status contains only the configured boolean. No-auth modules report authenticated immediately. External modules publish their instructions but no managed status stream or mutation controls.

The auth registry is separate from model capability caching. Each GET /api/agent-auth reads current binding snapshots, and managed changes arrive through WebSockets; these values do not wait for the 24-hour/2-hour model-catalog TTL.

The access gate uses descriptor policy rather than a fixed provider list. A no-auth module marked satisfiesAccessGate opens it immediately; managed code/device/API-key modules require an authenticated binding. External authentication cannot satisfy the gate because Remote cannot observe it reliably. The current built-ins mark Claude, Codex, and Kimi as gate providers; MiniMax is managed but not a gate provider, and Antigravity is external.

The capability response has a providers array in registry order. Each provider includes its source (live or fallback), optional warning and structured unavailability reason, models, per-model reasoning efforts and service tiers, modes, model/control defaults, the module default flag, execution scopes, authentication metadata, and declared session/skill/browser/scheduling/execution-policy features. Omitting projectId selects the host/loose-chat scope. Supplying it requires admin status or project membership and selects that project's current container. Only the literal refresh=1 forces discovery; other values use the normal cache path. Refresh bypasses a completed entry but joins a same-scope discovery already in flight. The route does not start a stopped project.

The cache is backend-process memory, shared across web clients by execution scope. Fully live, warning-free results use a 24-hour TTL; any fallback or warning shortens the complete scope to 2 hours. A backend restart clears it. See Capability discovery for provider probes and all refresh triggers.

Each provider probe receives the same AGENT_CAPABILITY_TIMEOUT deadline. The default is 30 seconds for the provider's complete discovery operation; setting the Go-duration environment value to 0 disables the deadline. Providers are still probed concurrently, so the setting is not multiplied into a sequential whole-catalog timeout.

Project routes#

Every {id} project route first requires admin status or project membership. Resource-limit changes and project deletion add an admin-only check.

Chat routes#

All chat routes resolve the caller and enforce the chat's project membership. Loose chats have no project membership check.

Scheduled-task routes#

Browser routes use the signed user session. Agent routes require a short-lived bearer capability issued for one owner, chat, and project; they do not accept a platform session cookie. Agent-created tasks are forced to createdByAgent and start disabled until a user arms them.

Schedule request bodies cap at 64 KiB and reject unknown fields. Stored prompts cap at 32 KiB. The service re-checks the owner, chat, project, registration, and access on every fire.

Upload and auxiliary routes#

The upload access check happens when the random upload URL is created. Later chunk requests rely on possession of that URL.

WebSocket routes#

Chat and project-terminal membership is checked before the WebSocket upgrade. Removing a member prevents future checked connections, but the backend does not currently close or reauthorize that member's already-open sockets.

Realtime channels#

Chat reconnect and replay#

The workspace and chat streams send ping frames every 25 seconds. The frontend chat socket reconnects from 400 ms up to 5 seconds and requests only unseen sequences.

Chat event shapes#

Common status behavior#

• 400: invalid IDs, paths, values, or JSON.
• 401: missing or invalid session.
• 403: valid user without role or project access.
• 404: missing chat, project, user, file, or repository target.
• 409: running-chat conflict, dirty Git state, protected last-admin/member guardrail, duplicate project display name, or duplicate user.
• 412: onboarding gate is incomplete.
• 413: upload or request body is too large.

Code map#

• Route composition: backend/internal/transport/transport.go
• HTTP server: backend/internal/transport/http/server.go
• Frontend route constants: frontend/src/config/routes.ts
• Chat socket: backend/internal/transport/ws/chat_socket.go
• Workspace socket: backend/internal/transport/ws/workspace_socket.go