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

> Explore Agent-Native authentication modes: dev auto-login, production Better Auth, and local CLI. Configure dev, production, and local environments using environment variables for secure access.

- Repository: [Builder.io/agent-native](https://github.com/BuilderIO/agent-native)
- Tags: how-to-guide
- Published: 2026-07-02

---

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

```bash
AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT=1

```

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

```bash
AUTH_SKIP_EMAIL_VERIFICATION=1

```

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

```bash
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:

```bash

# .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:

```bash

# .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:

```bash
ACCESS_TOKEN=demo-static-token

```

Client implementation:

```javascript
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:

```ts
// 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`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/client/embed-auth.ts) - Client-side token handling and MCP bridge logic
- [`packages/core/src/server/plugins/auth.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/server/plugins/auth.ts) - Server plugin mounting Better Auth via `autoMountAuth(app)`
- [`packages/core/src/a2a/auth-policy.ts`](https://github.com/BuilderIO/agent-native/blob/main/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.