Platform

Production readiness

Runtime probes, durable secret storage, deployment gates, authorization boundaries, and outbound network protections used by the production release.

API docs

Browse docs

On this page

01 Health and observability endpoints

reference

Route	Behavior	Authentication
GET /health	Liveness JSON with status and timestamp	Public
GET /ready	Checks PostgreSQL connectivity, pending Ecto migrations, and every configured Oban queue, including default, traces, evals, alerts, webhooks, billing, fleet, rollups, and replays. Unhealthy returns 503	Public
GET /metrics	Prometheus text export; responses are never cached. Production requires METRICS_BEARER_TOKEN (Authorization: Bearer) and METRICS_AUTH_ENABLED cannot be turned off	Dedicated bearer token required in production

02 Agent communication runtime

details

Canonical endpoints

Machine REST is rooted at /api/v1. Phoenix v2 realtime clients mint a 600-second token with POST /api/v1/socket_tokens, then connect at /socket/websocket and join the authenticated agent topic. There is no cacp.one, /v1, or /ws/v1 production fallback.

Ephemeral health state

Service-agent health reports, local history, and health aggregates are node-local ETS data. An application-node restart clears them; connected agents must report again. Do not use this view as a durable audit or monitoring archive.

03 Durable managed secrets

details

Required provider

Production requires SECRET_PROVIDER=postgres or SECRET_PROVIDER=aws_secrets_manager. The local ETS provider is allowed only in development and test because a restart destroys its values.

Stable encryption key

SECRETS_ENCRYPTION_KEY must be at least 32 bytes and remain stable across releases and nodes. PostgreSQL values are encrypted at rest; the key also stabilizes credential digests for every provider.

04 Release and migration behavior

details

Versioned, readiness-gated deploys

deploy.sh builds a versioned release, runs database migrations, switches the active symlink, restarts the service, and waits up to 30 seconds for /ready. A failed restart or readiness check rolls back when that rollback is safe.

Legacy local-secret migration

A still-running legacy local provider can be exported and imported automatically only when moving to PostgreSQL. The encrypted backup is retained. Automatic rollback is intentionally disabled after that import because restarting the old ETS-backed release would lose its values.

05 Authorization boundaries

details

Workspace roles

Owners and admins can manage workspace configuration; members can read and operate; auditors are read-only. Machine callers are authorized by exact credential scopes.

Platform administration

Platform access requires users.admin=true and a session authenticated within the last 10 minutes (sudo_mode? -10). A missing platform_role has owner access; explicit roles are viewer, operator, and owner. The console is /admin (overview, workspaces, users, operations, audit, access, partners).

06 Outbound request safety

details

SSRF and redirect controls

Production outbound HTTP requires HTTPS unless a trusted connector explicitly opts into private networking. Loopback, link-local, multicast, documentation, and other reserved ranges are always blocked; DNS results are validated and pinned, and automatic redirects are disabled.

07 Partner and engagement failed-auth throttle

details

30 HTTP 401/403s per client address per 60 seconds

Routes under /api/v1/partner and POST /api/v1/engagements/:engagement_id/events run AuthFailureThrottle. After 30 failed authentications from one client address in 60 seconds the next attempt is HTTP 429 with detail "Too many failed authentication attempts. Please retry later." Only 401 and 403 count; other statuses do not.

Related docs