OpenParable
Skip to content
← Back to skills

Server Plugins

Development
server-plugins

Server Plugins is an Agent Skill for development published in the BuilderIO/agent-native repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Framework server plugins and the `/_agent-native/` route namespace. Use when adding a custom server plugin, deciding whether to create an `/api/` route vs an action, or debugging auto-mounted framework routes.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/BuilderIO/agent-native/blob/HEAD/.agents/skills/server-plugins/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/server-plugins, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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/:

PluginDefault behaviorCustomize when
agent-chatAgent chat endpointsCustom mentionProviders or systemPrompt
authAuth middlewareCustom publicPaths or Google OAuth config
core-routes/_agent-native/poll, /_agent-native/ping, etcCustom envKeys or sseRoute
resourcesResource CRUDRarely
terminalTerminal emulatorRarely

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/:name endpoint or the React action hooks.

Auto-mounted framework routes

RoutePurpose
GET /_agent-native/pollPolling endpoint for DB change detection
GET /_agent-native/eventsSSE endpoint for real-time sync
GET /_agent-native/pingHealth check
GET/PUT/DELETE /_agent-native/application-state/:keyApplication state CRUD
GET/PUT/DELETE /_agent-native/application-state/compose/:idCompose draft CRUD
POST /_agent-native/agent-chatAgent chat SSE endpoint
GET /_agent-native/agent-chat/mentionsMention search for @-tagging
GET /_agent-native/env-statusEnv key configuration status
POST /_agent-native/env-varsSave 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/:nameAuto-mounted action endpoints
/_agent-native/available-clisAvailable CLI tools
/_agent-native/agent-terminal-infoTerminal connection info
/_agent-native/collab/*Real-time collaboration (see real-time-collab)
/_agent-native/a2aA2A 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/ routes
  • authentication — Auth middleware and session handling
  • portability — Use H3 (not Express) for all routes