Agent-Native Authentication Modes: Dev, Production, and Local Configuration Guide

Agent-Native supports three core authentication contexts—development auto-login, production-grade Better Auth with optional MCP OAuth, and local CLI identity—each configured via environment variables and server plugins in the BuilderIO/agent-native repository.

Agent-Native ships with a flexible authentication layer built on Better Auth, designed to accommodate everything from rapid local development to secure production deployments. Understanding the distinct authentication modes—development-time convenience features, production-ready identity flows, and local CLI-specific authentication—is essential for securing your applications while maintaining developer velocity.

Understanding Agent-Native Authentication Modes

The authentication architecture documented in packages/core/docs/content/authentication.mdx defines three primary operational modes that govern how users and agents establish identity.

Development Mode: Auto-Dev Account

When running locally with pnpm dev, Agent-Native automatically creates a throwaway dev account and signs the developer in to streamline the development workflow. This behavior applies only when a fresh development database is detected and is implemented specifically to accelerate the development feedback loop.

To disable this automatic login, set the environment variable:

AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT=1

For QA environments or preview builds where email verification is unnecessary, set:

AUTH_SKIP_EMAIL_VERIFICATION=1

To completely bypass all login UI for demos or automated testing—never use this in production—set:

AUTH_DISABLED=true

This runs every request as a single shared user and is documented in the environment variables section of the authentication MDX file.

Production Mode: Identity Providers

In production, Agent-Native offers three distinct strategies for handling authentication, ranging from built-in Better Auth to custom external providers.

Default Better Auth provides standard email/password and social-provider login (Google, GitHub, etc.) via the autoMountAuth(app) function. The framework automatically mounts the Better Auth server plugin, making it the simplest production configuration.

Remote MCP OAuth enables an OAuth 2.1 flow with PKCE for external MCP clients like Claude Code or ChatGPT connectors. These programmatic agents obtain access tokens by calling the app's MCP endpoint at /_agent-native/mcp, which acts as a protected resource and redirects 401 challenges to the Well-Known OAuth discovery document.

Custom Bring-Your-Own-Auth (BYOA) allows integration with external identity providers such as Clerk, Auth0, or Firebase by supplying a custom getSession callback in a server plugin.

Local Mode: CLI Identity

The AUTH_MODE=local setting alters only the CLI/agent identity used when running pnpm action. When set to local, the CLI runs as a deterministic dev user rather than a random one, ensuring reproducible tests. This flag does not affect the browser login flow or end-user authentication, as clarified in the authentication documentation.

Configuring Development Authentication

Development configuration focuses on convenience while maintaining security boundaries. The default behavior creates ephemeral accounts to eliminate setup friction.

To configure a development-friendly environment, create a .env file with:

# .env (local development)

AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT=0   # keep auto-dev account

AUTH_SKIP_EMAIL_VERIFICATION=1           # don't send verification emails

These settings are referenced in packages/core/docs/content/authentication.mdx and control the behavior of the development server when it detects a fresh database.

Production Environment Variables

Production configuration requires explicit credential management and security hardening. The following environment variables, documented in the Environment Variables table of the authentication MDX file, control production behavior:

Variable	Effect
BETTER_AUTH_SECRET	Signing key for Better Auth JWTs (auto-generated if omitted)
GOOGLE_SIGN_IN_CLIENT_ID / GOOGLE_SIGN_IN_CLIENT_SECRET	Low-scope Google OAuth client for normal app login
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET	Legacy/high-scope client used by templates needing Google API access
GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET	Enable GitHub login
ACCESS_TOKEN / ACCESS_TOKENS	Static bearer tokens for MCP clients that cannot perform OAuth
OAUTH_STATE_SECRET	Random 32+ character secret used to HMAC-sign OAuth state payloads (required in production)
COOKIE_DOMAIN / AGENT_NATIVE_SHARE_COOKIE_DOMAIN	Controls cookie realm sharing across sub-domains
AGENT_NATIVE_WORKSPACE	When set to 1, all apps in a workspace share a single session realm

Example production configuration:

# .env.production

BETTER_AUTH_SECRET=$(openssl rand -hex 32)
GOOGLE_SIGN_IN_CLIENT_ID=YOUR_CLIENT_ID
GOOGLE_SIGN_IN_CLIENT_SECRET=YOUR_CLIENT_SECRET
OAUTH_STATE_SECRET=$(openssl rand -hex 32)

Implementing Remote MCP OAuth

The MCP endpoint (/_agent-native/mcp) supports standard OAuth 2.1 flows for programmatic access. Clients receiving a 401 challenge are redirected to the Well-Known OAuth discovery document, then perform dynamic client registration followed by a PKCE exchange.

To enable this flow, no additional configuration is required beyond standard Better Auth setup. The framework automatically guards MCP routes and issues signed access tokens upon successful OAuth completion, as implemented in the server authentication plugins.

For clients that cannot perform OAuth, use static bearer tokens:

ACCESS_TOKEN=demo-static-token

Client implementation:

const resp = await fetch("https://mail.agent-native.com/_agent-native/mcp", {
  headers: { Authorization: `Bearer ${process.env.ACCESS_TOKEN}` },
});

Custom Authentication Implementation

For organizations requiring external identity providers, implement a custom getSession callback in a server plugin:

// packages/your-app/server/plugins/auth.ts
import { createAuthPlugin } from "@agent-native/core/server";
import { verifyWithClerk } from "./clerk";

export default createAuthPlugin({
  getSession: async (event) => {
    const clerkSession = await verifyWithClerk(event);
    if (!clerkSession) return null;
    return {
      email: clerkSession.email,
      userId: clerkSession.userId,
      name: clerkSession.firstName,
    };
  },
  publicPaths: ["/api/webhooks"], // optional: paths that bypass auth
});

This pattern allows integration with any identity provider while maintaining compatibility with Agent-Native's session management. The createAuthPlugin helper is available in @agent-native/core/server and the implementation details are documented in the Bring Your Own Auth section of the authentication MDX file.

Key Source Files

Authentication logic is distributed across several core packages:

• packages/core/docs/content/authentication.mdx - Core documentation describing auth modes and environment variables
• packages/core/src/client/embed-auth.ts - Client-side token handling and MCP bridge logic
• packages/core/src/server/plugins/auth.ts - Server plugin mounting Better Auth via autoMountAuth(app)
• packages/core/src/a2a/auth-policy.ts - JWT verification policies for MCP access tokens

Summary

• Development mode provides automatic dev accounts via AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT and optional email verification skipping via AUTH_SKIP_EMAIL_VERIFICATION
• Production mode supports three strategies: Default Better Auth (email/social), Remote MCP OAuth (PKCE for programmatic agents), and Custom BYOA (external providers like Clerk)
• Local mode (AUTH_MODE=local) controls only CLI identity for deterministic testing, not browser authentication
• Security-critical variables include BETTER_AUTH_SECRET, OAUTH_STATE_SECRET, and AUTH_DISABLED (which must never be enabled in production)
• Remote MCP access can use OAuth 2.1 flows or static ACCESS_TOKEN values for clients lacking UI capabilities

Frequently Asked Questions

What is the difference between development and production authentication modes?

Development mode automatically creates throwaway accounts and can skip email verification for rapid iteration, while production mode requires explicit configuration of secrets, OAuth credentials, and state management. The development auto-login activates only when a fresh database is detected and can be disabled via AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT=1.

How do I disable the login UI for demos or testing?

Set AUTH_DISABLED=true in your environment variables to run all requests as a single shared user without displaying login screens. This configuration must never be used in production environments with real user data, as it completely bypasses authentication checks.

Can I use Clerk, Auth0, or Firebase instead of Better Auth?

Yes, Agent-Native supports custom authentication through the Bring-Your-Own-Auth pattern. Implement a getSession callback in a server plugin using createAuthPlugin from @agent-native/core/server to verify sessions with external providers. This allows integration with Clerk, Auth0, Firebase, or any other identity service while maintaining compatibility with the framework's session handling.

What does AUTH_MODE=local actually configure?

AUTH_MODE=local affects only the identity used by CLI commands and agent actions (such as pnpm action), causing them to run as a deterministic dev user rather than a random one. This setting does not impact the browser-based login flow or end-user authentication, which continues to use the configured production authentication mode.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}