# How to Configure Agent-Native: Environment Variables, Templates, and CLI Setup

> Configure Agent-Native effortlessly. Set up environment variables, templates, and CLI for your project. Get started with Builder.io Agent-Native today.

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

---

**To configure Agent-Native, create a `.env` file in your project root with `DATABASE_URL`, `BUILDER_IO_API_KEY`, and `NEXT_PUBLIC_AGENT_APP_ID`, then run `pnpm dev` to start the Nitro server and load the configuration.**

Agent-Native is a full-stack framework by BuilderIO that integrates AI agents directly into real applications. Configuration is deliberately minimal, relying on environment variables and a JSON manifest to wire together the database, Builder.io API, and frontend at runtime.

## Environment Variable Configuration

Agent-Native reads all critical settings from `process.env` at runtime. These values are consumed across the monorepo, from the Drizzle SQL layer in [`packages/core/src/db.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/db.ts) to the Nitro server initialization in [`packages/core/src/server.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/server.ts).

### Required Environment Variables

You must provide three core variables in your `.env` file:

- **`DATABASE_URL`** – The PostgreSQL connection string used by Drizzle in [`packages/core/src/db.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/db.ts). Example: `postgresql://user:pass@localhost:5432/agent_native`.
- **`BUILDER_IO_API_KEY`** – Your Builder.io API key (e.g., `sbx_…`) read by the shared app config in [`packages/shared-app-config/templates.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/shared-app-config/templates.ts).
- **`NEXT_PUBLIC_AGENT_APP_ID`** – The public identifier for your app exposed to the frontend, also defined in [`packages/shared-app-config/templates.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/shared-app-config/templates.ts).

### Optional Configuration

The framework supports additional runtime tuning:

- **`PORT`** – Sets the Nitro server port (default: `3000`), read in [`packages/core/src/server.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/server.ts).
- **Feature flags** – Variables like `ENABLE_ANALYTICS` are accessed throughout the codebase via `process.env` to toggle optional capabilities.

## Quick Start with the Create CLI

The official quick-start wizard automates configuration for new projects:

```bash
npx @agent-native/core@latest create my-app
cd my-app
pnpm install
pnpm dev

```

During execution, the CLI:

1. Copies a template (e.g., `templates/calendar` or `templates/content`) into your workspace.
2. Generates an `.env` file from the template’s `env.example` and your CLI inputs.
3. Installs the `skills` CLI (`packages/skills`) for adding optional capabilities later.

## Manual Configuration for Existing Projects

If you are integrating Agent-Native into an existing repository, configure it manually:

1. Create an `.env` file in the project root by copying from your chosen template’s `env.example` (e.g., `templates/calendar/.env.example`).
2. Populate the required values:

```env
DATABASE_URL=postgresql://user:pass@localhost:5432/agent_native
BUILDER_IO_API_KEY=sbx_XXXXXXXXXXXXXXXX
NEXT_PUBLIC_AGENT_APP_ID=my-app
PORT=3000

```

3. Run `pnpm dev` – Nitro automatically loads the environment and passes values to the server, SQL layer, and frontend.

## Runtime Configuration via agent-native.json

Each template includes an [`agent-native.json`](https://github.com/BuilderIO/agent-native/blob/main/agent-native.json) manifest (located in paths like [`templates/calendar/agent-native.json`](https://github.com/BuilderIO/agent-native/blob/main/templates/calendar/agent-native.json)). These manifests declare built-in apps, required environment variables, and template-specific resources such as sync-config JSON. The framework reads these manifests at startup to validate that required environment variables are present.

## Adding Skills with the CLI

Extend your application by installing optional skills via the CLI installed during the create step:

```bash
pnpm skills add visual-plan

```

This command invokes the logic in [`packages/skills/src/install.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/skills/src/install.ts) to inject the `visual-plan` capability into your workspace.

## Accessing Configuration in Code

Access environment variables directly via `process.env` inside actions or server code:

```typescript
// src/actions/send-email.ts
import { defineAction } from '@agent-native/core';
import { z } from 'zod';
import { db } from '@/db';

export default defineAction({
  schema: z.object({
    emailId: z.string(),
    body: z.string(),
  }),
  run: async ({ emailId, body }) => {
    const apiKey = process.env.BUILDER_IO_API_KEY!;
    await db.insert('replies').values({ emailId, body, apiKey });
  },
});

```

## Summary

- **Agent-Native configuration** relies on a `.env` file containing `DATABASE_URL`, `BUILDER_IO_API_KEY`, and `NEXT_PUBLIC_AGENT_APP_ID`.
- **Source files** consuming these variables include [`packages/core/src/db.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/db.ts), [`packages/shared-app-config/templates.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/shared-app-config/templates.ts), and [`packages/core/src/server.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/server.ts).
- **Quick start** uses `npx @agent-native/core@latest create` to scaffold projects and generate environment files.
- **Manual setup** requires copying `env.example` from your chosen template and populating the required values.
- **Skills** are added via `pnpm skills add <skill-name>` using the CLI logic in [`packages/skills/src/install.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/skills/src/install.ts).

## Frequently Asked Questions

### Where does Agent-Native read the database connection string?

Agent-Native reads `DATABASE_URL` from `process.env` in [`packages/core/src/db.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/db.ts), where it initializes the Drizzle ORM client. This single variable wires the entire SQL layer across the full-stack framework.

### Can I use the Agent-Native CLI to add features after creating a project?

Yes. After running the create wizard, use `pnpm skills add <skill-name>` (e.g., `pnpm skills add visual-plan`) to inject optional capabilities. This command executes the installer logic located in [`packages/skills/src/install.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/skills/src/install.ts).

### What is the purpose of the agent-native.json manifest file?

The [`agent-native.json`](https://github.com/BuilderIO/agent-native/blob/main/agent-native.json) file in each template directory (e.g., [`templates/calendar/agent-native.json`](https://github.com/BuilderIO/agent-native/blob/main/templates/calendar/agent-native.json)) defines runtime configuration including built-in apps, required environment variables, and template-specific resources. The framework validates these requirements at startup to ensure all necessary configuration is present.

### How do I expose environment variables to the frontend?

Prefix the variable with `NEXT_PUBLIC_`. For example, `NEXT_PUBLIC_AGENT_APP_ID` is defined in [`packages/shared-app-config/templates.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/shared-app-config/templates.ts) and automatically exposed to the browser-side code, while sensitive keys like `BUILDER_IO_API_KEY` remain server-side only unless explicitly prefixed.