# How to Install Agent-Native: Complete Setup Guide for the BuilderIO Monorepo

> Install Agent-Native easily with this comprehensive setup guide. Clone the repo, run pnpm install, and launch the dev server to get started with the BuilderIO monorepo.

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

---

**To install Agent-Native, clone the BuilderIO/agent-native repository, run `pnpm install` from the root to resolve the monorepo workspace dependencies, and launch the development server with `pnpm dev` to access the UI at `http://localhost:3000`.**

Agent-Native is a monorepo containing reusable AI packages and template applications for building agent-driven interfaces. This guide covers how to install Agent-Native from source using pnpm workspaces, including building the TypeScript packages and starting the Nitro-based development server.

## Prerequisites

Before beginning the Agent-Native installation, ensure you have **pnpm** installed on your system. The repository relies on pnpm workspaces defined in [`pnpm-workspace.yaml`](https://github.com/BuilderIO/agent-native/blob/main/pnpm-workspace.yaml) to link internal packages and templates. While Node.js is required, the specific version constraints are enforced through the root [`package.json`](https://github.com/BuilderIO/agent-native/blob/main/package.json) engine requirements.

## Step-by-Step Agent-Native Installation

### 1. Clone the Repository

Start by cloning the official repository from GitHub:

```bash
git clone https://github.com/BuilderIO/agent-native.git
cd agent-native

```

This downloads the entire monorepo including the `packages/` directory (containing core, scheduling, pinpoint, and embedding libraries) and the `templates/` directory (containing sample applications like videos, calendar, and chat).

### 2. Install Monorepo Dependencies

Run the following command from the repository root to install all dependencies:

```bash
pnpm install

```

This command reads the [`pnpm-workspace.yaml`](https://github.com/BuilderIO/agent-native/blob/main/pnpm-workspace.yaml) file, which defines the workspace globs:

```yaml
packages:
  - "packages/*"
  - "templates/*"

```

pnpm creates a shared `node_modules/.pnpm` store and symlinks each package, ensuring that templates can import internal packages without version conflicts. This single command resolves inter-package imports for the entire workspace.

### 3. Build the Workspace

Compile the TypeScript sources and prepare production bundles:

```bash
pnpm run build

```

This triggers the build script defined in [`package.json`](https://github.com/BuilderIO/agent-native/blob/main/package.json), which executes:
1. **TypeScript compilation** (`tsc --build`) for all packages in the `packages/` directory
2. **Vite bundling** for each template to generate production-ready assets
3. **Nitro server pre-rendering** for SSR entry points like [`ssr-entry.ts`](https://github.com/BuilderIO/agent-native/blob/main/ssr-entry.ts)

### 4. Launch the Development Server

Start the combined Nitro API and Vite development server:

```bash
pnpm dev

```

This command initializes the `_agent-native` Nitro API alongside the Vite dev server, making the UI accessible at `http://localhost:3000`. The configuration supports hot-module replacement, so changes to source files trigger instant browser refreshes.

## Understanding the Monorepo Structure

The Agent-Native repository organizes code into two primary directories:

- **`packages/`** – Core libraries including `core`, `scheduling`, `pinpoint`, `embedding`, and `desktop-app`. These packages provide the runtime, agent surfaces, and data models.
- **`templates/`** – Self-contained sample applications (e.g., `templates/videos`, `templates/calendar`). Each template contains its own Vite configuration, TypeScript settings, and server entry points.

The workspace configuration ensures that any template can import from `packages/core` or other internal modules using standard import statements, with pnpm handling the symlinking automatically.

## Running Individual Templates

After completing the root installation, you can run specific templates independently. To launch the videos template:

```bash
cd templates/videos
pnpm dev

```

This starts a template-specific Vite dev server while maintaining access to the shared packages. The videos template demonstrates a fully-functional Agent-Native demo featuring a chat UI, real-time sync, and an active AI agent surface.

## Installing the VS Code Extension

The repository includes a VS Code extension located in `packages/vscode-extension/`. After running `pnpm install` at the root, open the repository in VS Code and run **"Extension: Debug"** from the command palette to launch the extension host. Refer to [`packages/vscode-extension/README.md`](https://github.com/BuilderIO/agent-native/blob/main/packages/vscode-extension/README.md) for specific debugging configurations.

## Adding Skills via CLI

Agent-Native supports extensibility through skills (such as `visual-recap` or `design-exploration`). After installation, add a skill to any template using:

```bash
npx @agent-native/core@latest skills add BuilderIO/agent-native --skill <skill-name>

```

This CLI command resolves the matching core runtime version, registers the skill, and updates the template's [`package.json`](https://github.com/BuilderIO/agent-native/blob/main/package.json) automatically. Documentation for skill management is available in [`templates/plan/README.md`](https://github.com/BuilderIO/agent-native/blob/main/templates/plan/README.md).

## Summary

- **Clone** the BuilderIO/agent-native repository to access the full pnpm workspace monorepo
- **Run `pnpm install`** at the root to resolve dependencies for all packages and templates defined in [`pnpm-workspace.yaml`](https://github.com/BuilderIO/agent-native/blob/main/pnpm-workspace.yaml)
- **Execute `pnpm dev`** to start the Nitro API and Vite development server on `http://localhost:3000`
- **Use `pnpm run build`** to compile TypeScript sources and create production bundles for all templates
- **Navigate to individual templates** (e.g., `templates/videos`) and run `pnpm dev` to develop specific applications

## Frequently Asked Questions

### What are the system requirements for installing Agent-Native?

Agent-Native requires Node.js and pnpm to manage the monorepo workspace. The specific Node.js version constraints are defined in the root [`package.json`](https://github.com/BuilderIO/agent-native/blob/main/package.json) engine field. Since the project uses pnpm workspaces for dependency management, you cannot use npm or yarn to install dependencies correctly.

### Why does Agent-Native use pnpm workspaces instead of npm?

The [`pnpm-workspace.yaml`](https://github.com/BuilderIO/agent-native/blob/main/pnpm-workspace.yaml) file defines the monorepo structure, specifying that both `packages/*` and `templates/*` directories belong to the workspace. pnpm creates a content-addressable store at `node_modules/.pnpm` and symlinks packages, which prevents version conflicts between templates and ensures that internal packages like `@agent-native/core` are properly linked for local development.

### How do I run a specific template after installing Agent-Native?

After completing the root installation, navigate to any template directory (such as `templates/videos` or `templates/calendar`) and run `pnpm dev`. Each template contains its own Vite configuration and server entry point ([`ssr-entry.ts`](https://github.com/BuilderIO/agent-native/blob/main/ssr-entry.ts)), but inherits resolved dependencies from the workspace root, allowing independent development of specific applications.

### How do I add skills to an Agent-Native template after installation?

Use the Agent-Native CLI command `npx @agent-native/core@latest skills add BuilderIO/agent-native --skill <skill-name>`. This resolves the correct core runtime version, registers the skill with the template, and updates the local [`package.json`](https://github.com/BuilderIO/agent-native/blob/main/package.json). Skills provide additional capabilities like visual recap or design exploration, and can be managed per-template after the initial installation is complete.