# Prerequisites for Using Agent-Native: Node.js and pnpm Setup Guide

> Set up Node.js v24+ and pnpm v10+ for Agent-Native. This guide covers the essential prerequisites for running the Agent-Native monorepo framework and development server smoothly.

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

---

**Agent-Native requires Node.js version 22 or higher (v24+ recommended) and pnpm version 10 or higher to run the monorepo framework and its development server.**

BuilderIO/agent-native is a modern, monorepo-based framework for building AI agents that enforces strict runtime requirements. Before cloning the repository or creating a new application, you must install two specific prerequisites for using agent-native: a recent Node.js runtime and the pnpm package manager. The framework performs automated version checks at startup to prevent compatibility issues.

## Core Runtime Requirements

The agent-native framework splits its tooling between runtime dependencies and workspace management. According to the [`DEVELOPMENT.md`](https://github.com/BuilderIO/agent-native/blob/main/DEVELOPMENT.md) file in the repository root, the system requires specific versions of Node.js and pnpm to function correctly.

### Node.js Version Requirements

The framework code in [`packages/core/src/cli/index.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/cli/index.ts) implements a runtime check that validates your Node.js version upon execution. If your Node version is below 22, the CLI exits with a clear error message. While version 22 is the minimum, the development team recommends Node.js v24 or higher for optimal performance and compatibility with modern JavaScript features.

### pnpm and Workspace Management

Agent-native uses pnpm workspaces to manage its monorepo structure, defined in [`pnpm-workspace.yaml`](https://github.com/BuilderIO/agent-native/blob/main/pnpm-workspace.yaml) at the repository root. The project requires **pnpm ≥ 10** to handle dependency resolution correctly across packages. You can enable the exact version pinned in the repository using Corepack, which eliminates version mismatches between environments.

## Step-by-Step Installation

Follow these commands to verify and install the required prerequisites for using agent-native:

```bash

# Install Node.js 24 (recommended) using nvm

nvm install 24
nvm use 24

# Enable pnpm via corepack (uses version pinned in repo)

corepack enable

# Verify installation

node -v   # Expected: v24.x.x or higher

pnpm -v   # Expected: 10.x.x

```

Once the tools are installed, clone the repository and install workspace dependencies:

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

```

After installation, you can create a new application using the CLI:

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

```

## Template-Specific Prerequisites

While the core framework requires only Node.js and pnpm, individual templates may have additional dependencies. For example, the desktop template documented in [`templates/desktop/README.md`](https://github.com/BuilderIO/agent-native/blob/main/templates/desktop/README.md) requires the Tauri toolchain for building native applications. These requirements are optional and only necessary when working with specific templates that extend beyond the core framework capabilities.

## Key Configuration Files

Understanding these files helps troubleshoot environment issues:

- **[`DEVELOPMENT.md`](https://github.com/BuilderIO/agent-native/blob/main/DEVELOPMENT.md)** - Documents the exact version requirements and workspace structure
- **[`package.json`](https://github.com/BuilderIO/agent-native/blob/main/package.json)** - Declares core dependencies and npm scripts that rely on pnpm
- **[`pnpm-workspace.yaml`](https://github.com/BuilderIO/agent-native/blob/main/pnpm-workspace.yaml)** - Defines the monorepo layout and package resolution strategy
- **[`packages/core/src/cli/index.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/cli/index.ts)** - Contains the runtime Node.js version enforcement logic

## Summary

- Agent-native requires **Node.js ≥ 22** (v24+ recommended) and **pnpm ≥ 10** as core prerequisites
- The framework validates Node.js versions at runtime via [`packages/core/src/cli/index.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/cli/index.ts)
- Use `corepack enable` to automatically manage the correct pnpm version pinned in the repository
- No additional system dependencies like Docker or Rust are required for the core framework
- Template-specific prerequisites (such as Tauri for desktop apps) are documented in individual template READMEs

## Frequently Asked Questions

### Can I use npm or yarn instead of pnpm with agent-native?

No. The agent-native monorepo is explicitly configured for pnpm workspaces as defined in [`pnpm-workspace.yaml`](https://github.com/BuilderIO/agent-native/blob/main/pnpm-workspace.yaml). While you might install the CLI globally with npm, running the workspace or development server requires pnpm to resolve inter-package dependencies correctly.

### What happens if I try to run agent-native with Node.js 20?

The CLI will exit immediately with a version error. The runtime check in [`packages/core/src/cli/index.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/cli/index.ts) enforces the minimum Node.js version 22 requirement before any framework code executes, preventing cryptic compatibility errors later in the development process.

### Do I need Docker installed to use agent-native?

No. Docker is not listed as a prerequisite in [`DEVELOPMENT.md`](https://github.com/BuilderIO/agent-native/blob/main/DEVELOPMENT.md) or required for the core framework. However, specific deployment templates or optional development environments might reference Docker configurations in their respective documentation.

### How do I upgrade from an older pnpm version to version 10?

Run `corepack enable` in the repository root after cloning. This command automatically respects the `packageManager` field in [`package.json`](https://github.com/BuilderIO/agent-native/blob/main/package.json) and activates the exact pnpm version (≥10) pinned by the agent-native team, eliminating manual version management.