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

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 to link internal packages and templates. While Node.js is required, the specific version constraints are enforced through the root package.json engine requirements.

Step-by-Step Agent-Native Installation

1. Clone the Repository

Start by cloning the official repository from GitHub:

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:

pnpm install

This command reads the pnpm-workspace.yaml file, which defines the workspace globs:

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:

pnpm run build

This triggers the build script defined in 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

4. Launch the Development Server

Start the combined Nitro API and Vite development server:

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:

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

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 automatically. Documentation for skill management is available in 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
• 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 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 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), 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. Skills provide additional capabilities like visual recap or design exploration, and can be managed per-template after the initial installation is complete.

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