# How to Set Up PrimeIntellect-ai/prime-agent Locally: Complete Installation Guide > Install PrimeIntellect-ai/prime-agent locally with our complete guide. Choose the installer script or clone the repo and run via TypeScript CLI for a seamless setup. - Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent) - Tags: getting-started - Published: 2026-08-16 --- **To set up Prime Agent locally, either run the official installer script for a pre-built bundle or clone the repository and launch via the TypeScript CLI using [`./prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/./prime-agent.sh).** Prime Agent is a self-improving coding assistant built on a persistent IPython kernel, a daemon-backed worker architecture, and a plug-in model provider layer. This guide walks through both methods to install and run PrimeIntellect-ai/prime-agent from source, with complete commands and architecture context drawn directly from the codebase. --- ## Prerequisites for Local Setup Before installing, verify your environment meets these requirements: - **Node.js 22.8+** – Required for running from source (checked in [`packages/coding-agent/docs/development.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/development.md)) - **Python 3.8+** – For the IPython kernel environment - **macOS or Linux** – Primary supported platforms - **Git** – For cloning the repository Confirm your Node version with: ```bash node --version ``` --- ## Method 1: Install Pre-Built Release (Recommended) The fastest way to set up Prime Agent locally uses the official installer script. This downloads a bundled JavaScript build and installs the `prime-agent` command globally. ```bash # Download and run the official installer curl -fsSL https://app.primeintellect.ai/prime-agent/install.sh | sh ``` After installation, verify the command is available: ```bash prime-agent --version ``` Navigate to any project directory and launch: ```bash cd /path/to/your/project prime-agent ``` --- ## Method 2: Install From Source For development or customization, clone the repository and run the TypeScript CLI directly via the launcher script. ### Step 1: Clone and Install Dependencies ```bash git clone https://github.com/PrimeIntellect-ai/prime-agent cd prime-agent npm ci ``` ### Step 2: Launch With the Development Launcher The [`prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/prime-agent.sh) script at repository root handles the build-vs-source decision and preserves your current working directory: ```bash ./prime-agent.sh ``` This launcher parses command-line flags, selects between bundled builds or runs the TypeScript CLI via `tsx`, as implemented in the shell script logic. --- ## Configure the IPython Kernel Environment Prime Agent's core execution relies on a persistent IPython kernel. The helper script [`scripts/setup-kernel-venv.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/scripts/setup-kernel-venv.sh) automates virtual environment creation and kernel bootstrap: ```bash # Creates venv and launches kernel bootstrap CLI scripts/setup-kernel-venv.sh ``` This step is optional for basic operation—the daemon supervisor spawns kernel processes automatically—but useful for debugging or isolated Python environments. --- ## Authentication Setup Prime Agent supports two authentication modes against provider APIs located in `packages/ai`. ### Option A: Subscription Login (Interactive) Launch Prime Agent and use the built-in TUI command: ``` /login ``` This flow is handled in [`packages/coding-agent/src/cli.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/cli.ts), which implements slash command parsing and daemon connection. ### Option B: API Key via Environment Variable ```bash export ANTHROPIC_API_KEY=sk-... export OPENAI_API_KEY=sk-... # Run with explicit credentials prime-agent ``` Use the `--no-env` flag to clear authentication variables if needed: ```bash prime-agent --no-env ``` --- ## Understanding the Startup Architecture Knowing how components interact helps debug setup issues. The startup flow defined in [`packages/coding-agent/docs/architecture.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/architecture.md) proceeds as follows: 1. **Launcher** ([`prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/prime-agent.sh)) → decides bundled JS or `tsx` → starts CLI 2. **CLI** ([`packages/coding-agent/src/cli.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/cli.ts)) → opens connection to daemon supervisor 3. **Daemon supervisor** → spawns session worker if needed 4. **Session worker** → creates root `AgentSessionRuntime` → launches IPython kernel 5. **Model provider streams** (`packages/ai`) → generate text/tool calls, kernel executes Python 6. **Persistence layer** → writes transcripts and artifacts to `~/.prime/agent/sessions/` The `AgentSessionRuntime` class in [`packages/coding-agent/src/core/agent-session-runtime.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/agent-session-runtime.ts) coordinates the scheduler, kernel, and tool execution loop. --- ## Configuration Directory Structure Prime Agent reads configuration from two locations, as documented in [`packages/coding-agent/docs/development.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/development.md): | Location | Purpose | |----------|---------| | `~/.prime/agent/` | User-wide configuration and session storage | | `.prime/agent/` | Project-local overrides (in working directory) | Session transcripts persist under `~/.prime/agent/sessions/` for audit and replay. --- ## Managing Persistent Sessions Prime Agent supports detaching and reattaching to long-running agent processes: ```bash # List all running agents prime-agent agents # Reattach to specific agent ID prime-agent attach ``` This daemon-backed architecture allows agents to continue execution even when the TUI disconnects. --- ## Key Source Files Reference | File | Description | |------|-------------| | [`prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/prime-agent.sh) | Launcher script with `--no-env` and `--dist` flags | | [`packages/coding-agent/src/cli.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/cli.ts) | CLI entry point, TUI, slash command parser | | [`packages/coding-agent/src/core/agent-session-runtime.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/agent-session-runtime.ts) | Root session runtime and scheduler | | [`scripts/setup-kernel-venv.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/scripts/setup-kernel-venv.sh) | IPython kernel bootstrap helper | | [`packages/coding-agent/docs/architecture.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/architecture.md) | Component diagram and responsibilities | | [`packages/coding-agent/docs/development.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/development.md) | Node version, validation commands, config paths | | `packages/ai` | Provider adapters (Anthropic, OpenAI, Bedrock) | | [`packages/coding-agent/docs/quickstart.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/quickstart.md) | Extended source installation steps | --- ## Summary - **Quick install**: Use `curl -fsSL ... | sh` for the pre-built release - **Source setup**: Clone, run `npm ci`, then launch with [`./prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/./prime-agent.sh) - **Kernel setup**: Optional [`scripts/setup-kernel-venv.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/scripts/setup-kernel-venv.sh) for isolated Python - **Authentication**: Interactive `/login` command or environment variables - **Architecture**: Daemon-supervised workers with persistent IPython kernel - **Config locations**: `~/.prime/agent/` (global) and `.prime/agent/` (project) --- ## Frequently Asked Questions ### What Node.js version is required to set up Prime Agent locally? Prime Agent requires Node.js 22.8 or newer when running from source. This requirement is documented in [`packages/coding-agent/docs/development.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/development.md). The pre-built installer bundles its own runtime and does not need Node installed. ### How does Prime Agent handle API authentication securely? Authentication flows through the `packages/ai` provider layer. You can either use the interactive `/login` command inside the TUI or export provider-specific API keys as environment variables. The `--no-env` flag clears these variables for isolated sessions. ### Where are Prime Agent sessions and transcripts stored? All session data persists to `~/.prime/agent/sessions/` by default. This includes conversation transcripts, executed code outputs, and tool call results. The daemon architecture ensures persistence even when the CLI disconnects and reattaches. ### Can I run Prime Agent without installing the pre-built bundle? Yes. Clone the repository, run `npm ci` to install dependencies, then execute [`./prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/./prime-agent.sh). This launcher script detects the source environment and runs the TypeScript CLI via `tsx` rather than the bundled JavaScript build.