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

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

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

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:

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 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 - Documents the exact version requirements and workspace structure
• package.json - Declares core dependencies and npm scripts that rely on pnpm
• pnpm-workspace.yaml - Defines the monorepo layout and package resolution strategy
• 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
• 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. 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 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 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 and activates the exact pnpm version (≥10) pinned by the agent-native team, eliminating manual version management.

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