Builder.io Server Plugins & Framework Routes
Default Plugins (auto-mount)
Five default plugins auto-mount when your app doesn't have a custom version in server/plugins/:
| Plugin | Default behavior | Customize when |
|---|---|---|
agent-chat |
Agent chat endpoints | Custom mentionProviders or systemPrompt |
auth |
Auth middleware | Custom publicPaths or Google OAuth config |
core-routes |
/_agent-native/poll, /_agent-native/ping, etc |
Custom envKeys or sseRoute |
resources |
Resource CRUD | Rarely |
terminal |
Terminal emulator | Rarely |
Only create plugin files for plugins you need to customize. Let defaults auto-mount.
Framework Route Namespace: /_agent-native/
All framework-level routes live under /_agent-native/ to avoid collisions with template-specific /api/* routes.
Hard rule
- ALL framework routes go under
/_agent-native/. - Templates own
/api/*only for route-only domain concerns such as uploads, streaming, webhooks, OAuth callbacks, or non-JSON protocols. - Never put framework routes under
/api/. - Never put template routes under
/_agent-native/— that namespace is reserved. - Never create
/api/*routes that only wrap, proxy, or re-export actions. Use the existing/_agent-native/actions/:nameendpoint or the React action hooks.
Auto-mounted framework routes
| Route | Purpose |
|---|---|
GET /_agent-native/poll |
Polling endpoint for DB change detection |
GET /_agent-native/events |
SSE endpoint for real-time sync |
GET /_agent-native/ping |
Health check |
GET/PUT/DELETE /_agent-native/application-state/:key |
Application state CRUD |
GET/PUT/DELETE /_agent-native/application-state/compose/:id |
Compose draft CRUD |
POST /_agent-native/agent-chat |
Agent chat SSE endpoint |
GET /_agent-native/agent-chat/mentions |
Mention search for @-tagging |
GET /_agent-native/env-status |
Env key configuration status |
POST /_agent-native/env-vars |
Save env vars |
/_agent-native/auth/* |
Authentication (login, session, logout) |
/_agent-native/google/* |
Google OAuth (callback, auth-url, etc.) |
/_agent-native/resources/* |
Resource CRUD |
/_agent-native/actions/:name |
Auto-mounted action endpoints |
/_agent-native/available-clis |
Available CLI tools |
/_agent-native/agent-terminal-info |
Terminal connection info |
/_agent-native/collab/* |
Real-time collaboration (see real-time-collab) |
/_agent-native/a2a |
A2A JSON-RPC endpoint (see a2a-protocol) |
Actions-First Approach
For standard CRUD and data operations, use defineAction in actions/ — the framework auto-mounts them as HTTP endpoints at /_agent-native/actions/:name. Only create custom /api/* routes for things actions can't do:
- File uploads with multipart form data
- Streaming responses
- Webhooks from external services
- OAuth callbacks
Before adding a route, inspect the existing action files. Reuse the action if it already encodes the business rule, or add a new action if the operation should be available to both the agent and the UI. A route whose implementation mostly calls an action is usually the wrong abstraction.
The Nitro Vite plugin handles both /api/ and /_agent-native/ prefixes via file-based routing in server/routes/.
Related Skills
actions— Prefer actions over custom/api/routesauthentication— Auth middleware and session handlingportability— Use H3 (not Express) for all routes