Deployment

Agent-native apps use Nitro under the hood, which means you can deploy to any platform with zero config changes — just set a preset.

Workspace Deploy: One Origin, Many Apps

If your project is a workspace, you can ship every app in it to a single origin with one command:

agent-native deploy
# https://your-agents.com/mail/*       → apps/mail
# https://your-agents.com/calendar/*   → apps/calendar
# https://your-agents.com/forms/*      → apps/forms

Each app is built with APP_BASE_PATH=/<name> and VITE_APP_BASE_PATH=/<name>, then packaged into dist/<name>/. Cloudflare Pages is the default preset and uses a generated dispatcher worker at dist/_worker.js; Netlify uses one function per app in .netlify/functions-internal/<app>-server plus generated redirects.

Same-origin deploy gives you two big wins for free:

• Shared login session — log into any app, every app is logged in.
• Zero-config cross-app A2A — tagging @calendar from mail is a same-origin fetch; no CORS, no JWT signing between siblings.

Publish the output with:

wrangler pages deploy dist

For Netlify unified deploys, use the Netlify preset:

agent-native deploy --preset netlify

Generated workspaces include a root netlify.toml that runs agent-native deploy --preset netlify --build-only, publishes dist, and points Netlify at .netlify/functions-internal.

Hosted workspace builds require A2A_SECRET in the deploy provider environment. This makes Slack, inbound webhooks, and cross-app A2A resume work through signed background processors. Local --build-only artifact checks still run without it.

Per-app independent deploy is still supported — just cd apps/<name> && agent-native build like a standalone scaffold.

How It Works

When you run agent-native build, Nitro builds both the client SPA and the server API into .output/:

.output/
  public/          # Built SPA (static assets)
  server/
    index.mjs      # Server entry point
    chunks/         # Server code chunks

The output is self-contained — copy .output/ to any environment and run it.

Setting the Preset

By default, Nitro builds for Node.js. To target a different platform, set the preset in your vite.config.ts:

import { defineConfig } from "@agent-native/core/vite";

export default defineConfig({
  nitro: {
    preset: "vercel",
  },
});

Or use the NITRO_PRESET environment variable at build time:

NITRO_PRESET=netlify agent-native build

Node.js (Default)

The default preset. Build and run:

agent-native build
node .output/server/index.mjs

Set PORT to configure the listen port (default: 3000).

Use the current Node.js LTS line for production deploys. As of May 2026, that is Node.js 24; Node.js 20 reached end-of-life on April 30, 2026 and no longer receives upstream security updates.

Docker

FROM node:24-slim AS build
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN corepack enable && pnpm install --frozen-lockfile
COPY . .
RUN pnpm build

FROM node:24-slim
WORKDIR /app
COPY --from=build /app/.output .output
COPY --from=build /app/data data
ENV PORT=3000
EXPOSE 3000
CMD ["node", ".output/server/index.mjs"]

Vercel

// vite.config.ts
export default defineConfig({
  nitro: { preset: "vercel" },
});

Deploy via the Vercel CLI or git push:

vercel deploy

Netlify

The Nitro netlify preset works well and, in practice, has given us much faster cold starts than Cloudflare Pages (~200ms TTFB vs ~9s) for templates that talk to external Postgres (Neon). Either set the preset in vite.config.ts:

// vite.config.ts
export default defineConfig({
  nitro: { preset: "netlify" },
});

…or set NITRO_PRESET=netlify at build time.

For a workspace, deploy every app from one Netlify site by running:

agent-native deploy --preset netlify

The workspace build writes static assets to dist/<app>/ and routes each app to its own Netlify function without forced redirects, so files like /mail/assets/... are served statically before the server function handles app routes.

Cloudflare Pages

// vite.config.ts
export default defineConfig({
  nitro: { preset: "cloudflare_pages" },
});

AWS Lambda

// vite.config.ts
export default defineConfig({
  nitro: { preset: "aws_lambda" },
});

Deno Deploy

// vite.config.ts
export default defineConfig({
  nitro: { preset: "deno_deploy" },
});

Environment Variables

Build / Runtime

Required in Production

These must be set before promoting an app to a real prod deploy. Missing values either fail-closed (the framework refuses to start / refuses to handle requests) or fall back to weaker behavior with a loud warning.

Auth & Identity

Inbound Webhooks

Inbound webhook handlers refuse forged requests when their signing secret is missing in production (was previously fail-open with a warning — see CHANGELOG / security audit fixes).

For local development of any of these integrations, set AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS=1 to opt back into the old "warn and accept" behavior — never set this in prod.

Security Configuration (Opt-in)

Defaults are strict; these flags relax behavior. Don't set them unless you specifically want the relaxed path.

Workspace .env Inheritance

Inside a workspace, the root .env is loaded into every app automatically, so shared keys like ANTHROPIC_API_KEY, A2A_SECRET, BETTER_AUTH_SECRET, and OAUTH_STATE_SECRET only need to be set once. Per-app apps/<name>/.env wins on conflict.

Generating Strong Secrets

For any secret marked "32+ char random" (BETTER_AUTH_SECRET, OAUTH_STATE_SECRET, A2A_SECRET, SECRETS_ENCRYPTION_KEY), generate fresh values with:

openssl rand -hex 32

Rotate them by replacing the env var on every instance and redeploying — sessions / OAuth state envelopes signed under the old key become invalid, so users may need to sign in again.

Updating UI in Production

One of agent-native's core features is that the agent can modify your app's source code — components, routes, styles, actions. During local development this works seamlessly because the agent has full filesystem access.

In a standard production deployment, however, the agent runs in production mode with access to app tools (actions, database, MCP) but not the filesystem. This means the agent can read and write data, run actions, and interact with external services — but it can't edit your React components or add new routes on a deployed instance.

Builder.io: Visual Editing in Production

Builder.io solves this by providing a managed cloud environment where the agent retains the ability to modify your app's UI in production. Connect your repo to Builder.io and prompt for UI changes directly — no redeploy needed.

How it works:

1. Connect your agent-native repo to Builder.io
2. Builder.io provides a cloud frame with the agent, visual editing, and real-time collaboration
3. Prompt the agent to make UI changes — it edits your components, routes, and styles live
4. Changes are committed back to your repo

See Frames for more on the embedded agent panel vs. cloud frame options.

Multi-instance deploys

Agent-native apps store all state in SQL via Drizzle and sync the UI via polling against the database — no file-system state, no sticky sessions, no in-memory caches. That means multi-instance and serverless deployments work out of the box: point every instance at the same DATABASE_URL and they converge automatically. See Key Concepts — Data in SQL and Portability.