Web App Routes

Route Map

Route	Purpose	Key actions
/	Landing + sign-in CTA	Privy login, pricing/features presentation
/dashboard	Agent list and management entry	Usage/limit snapshot, open agent, delete agent, create agent
/dashboard/create	New agent workflow	Create DB record + provision machine
/dashboard/agent/[id]	Agent operations	Start/stop/provision/delete/clone, runtime updates, shell, channel connect
/settings	Account, billing, and runtime governance	Update profile, checkout, credits, usage summary, billing portal, runtime spend approvals/policies, runtime delegations
/auth/device	Device flow approval UI	Approve user code for CLI/MCP login

Auth Behavior

• Protected routes redirect unauthenticated users to /.
• /auth/device requires authenticated user before approval call.

Polling and Live Updates

• Agent list: periodic refresh in useAgents().
• Agent detail: periodic refresh in useAgent() plus machine status polling during deploy/startup.
• Runtime update status: periodic refresh while machine exists.

Main Client APIs Used by Web Routes

Agent surfaces

• GET /api/agents
• POST /api/agents
• GET /api/agents/:id
• PATCH /api/agents/:id
• DELETE /api/agents/:id
• POST /api/agents/:id/provision
• POST /api/agents/:id/clone
• POST /api/agents/:id/start
• POST /api/agents/:id/stop
• GET /api/agents/:id/status
• GET /api/agents/:id/gateway-access
• GET /api/agents/:id/runtime-update-status
• POST /api/agents/:id/runtime-update-grant
• POST /api/agents/:id/connect-telegram
• POST /api/agents/:id/whatsapp-qr
• POST /api/agents/:id/whatsapp-wait

User and billing

• GET /api/users/me
• PATCH /api/users/me
• GET /api/billing/summary
• GET /api/billing/usage-summary
• POST /api/billing/checkout
• POST /api/billing/credits/checkout
• POST /api/billing/portal
• POST /api/billing/sync
• GET /api/billing/runtime-requests
• GET /api/billing/runtime-requests/:id
• POST /api/billing/runtime-requests/:id/approve
• POST /api/billing/runtime-requests/:id/deny
• GET /api/billing/runtime-spend-policies/:controllerAgentId
• POST /api/billing/runtime-spend-policies/:controllerAgentId
• DELETE /api/billing/runtime-spend-policies/:controllerAgentId
• GET /api/runtime/delegations
• POST /api/runtime/delegations
• DELETE /api/runtime/delegations/:id

Billing flow semantics

• Plan changes from web app always start with Stripe Checkout (POST /api/billing/checkout).
• This includes both upgrades and downgrades; the control plane does not expose a direct plan mutation endpoint.
• The web app expects return query params on /settings:
  • billing=success|cancel for subscription checkout.
  • billing=credits_success|credits_cancel for one-time credits checkout.

Billing redirect validation checklist

1. Start plan checkout from /settings and complete payment in Stripe test mode.
2. Verify redirect back to /settings?billing=success and that plan/entitlement cards refresh.
3. Start plan checkout again and cancel in Stripe.
4. Verify redirect back to /settings?billing=cancel and no plan/credit mutation.
5. Start credits checkout and complete payment.
6. Verify redirect back to /settings?billing=credits_success and credits balance increases.
7. Start credits checkout and cancel in Stripe.
8. Verify redirect back to /settings?billing=credits_cancel and credits balance is unchanged.

Device approval

• POST /api/auth/device/approve