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

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 to the Nitro server initialization in 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. 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.
• NEXT_PUBLIC_AGENT_APP_ID – The public identifier for your app exposed to the frontend, also defined in 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.
• 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:

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:

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 manifest (located in paths like 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:

pnpm skills add visual-plan

This command invokes the logic in 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:

// 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, packages/shared-app-config/templates.ts, and 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.

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, 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.

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

The agent-native.json file in each template directory (e.g., 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 and automatically exposed to the browser-side code, while sensitive keys like BUILDER_IO_API_KEY remain server-side only unless explicitly prefixed.

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