# How to Set Up PrimeAgent Locally: Complete Installation and Configuration Guide

> Learn how to set up PrimeAgent locally with this complete installation guide. Configure the modular coding assistant for efficient tool execution.

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: how-to-guide
- Published: 2026-08-14

---

**PrimeAgent is a self-improving coding assistant built on a modular architecture that separates the terminal UI, daemon supervision, session workers, and an IPython kernel for model-driven tool execution.**

Setting up PrimeAgent locally involves choosing between a pre-built release or building from source, then authenticating with a model provider to enable AI-powered coding assistance. This guide walks through both installation methods, explains the underlying architecture, and covers the detach/reattatch workflow that makes long-running autonomous tasks possible.

## PrimeAgent Architecture Overview

Understanding how the components interact helps explain why PrimeAgent can survive client restarts and handle background tasks. According to the PrimeIntellect-ai/prime-agent source code, the system consists of four main layers:

- **Interactive TUI / Headless Clients** — The front-end that renders output and accepts keystrokes. Run `prime-agent` for the interactive interface or `prime-agent -p` for headless execution. These clients communicate with the daemon via a local protocol.

- **Daemon Supervisor** — Routes commands, manages worker processes, and maintains a catalog of saved sessions. It isolates execution from the client but does **not** sandbox OS permissions. See [`packages/coding-agent/docs/architecture.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/architecture.md) for implementation details.

- **Session Worker** — Owns a single root `AgentSessionRuntime`, a scheduler, and a persistent IPython kernel. The root session can spawn **recursive subagents** that run in their own child runtimes, sharing the same provider and tool stack.

- **Model Providers** — Abstracted behind a unified streaming interface. Providers are selected via `/login` or environment-variable API keys. Supported providers are documented in [`packages/coding-agent/docs/providers.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/providers.md).

Session persistence stores all transcript events and generated artifacts as JSONL files under `~/.prime/agent/sessions/`, enabling detach/reattach semantics and replay of prior work.

## Installation Method 1: Pre-Built Release (Recommended)

The fastest way to set up PrimeAgent locally uses the official install script. This works on macOS and Linux systems.

```bash
curl -fsSL https://app.primeintellect.ai/prime-agent/install.sh | sh

```

After installation, the `prime-agent` binary becomes available in your PATH. Restart your terminal or run `source ~/.bashrc` (or equivalent) to refresh your environment.

## Installation Method 2: Build from Source

Building from source requires **Node 22 or newer**. This method is preferred for contributors or users needing the latest unreleased features.

```bash
git clone https://github.com/PrimeIntellect-ai/prime-agent
cd prime-agent
npm ci            # install workspace dependencies

./prime-agent.sh  # launches the agent from the source tree

```

The [`./prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/./prime-agent.sh) launcher script sets up the Node workspace and starts the daemon. This script is the recommended entry point when running from source rather than invoking Node directly.

## Authenticating with Model Providers

PrimeAgent requires a valid model provider to function. Two authentication methods are supported:

**Option A: Interactive Subscription Login**

```bash
cd /path/to/your/project
prime-agent       # opens the interactive TUI

/login            # built-in authentication UI

```

**Option B: Environment Variable API Key**

```bash
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...

# or other supported provider keys

prime-agent

```

See [`packages/coding-agent/docs/providers.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/providers.md) for the complete list of supported providers and their required environment variable names.

## Basic Usage Patterns

### Interactive TUI Sessions

Launch PrimeAgent in your project directory to start an interactive session:

```bash
cd /path/to/your/project
prime-agent

```

The TUI provides real-time output rendering and accepts natural language commands alongside standard shell input.

### Non-Interactive One-Shot Prompts

Execute single prompts without entering the interactive interface:

```bash
prime-agent -p "Summarize the codebase"
prime-agent -p @src/main.ts "Explain this module"

```

The `@file` syntax attaches file context to your prompt. This is useful in CI/CD pipelines or when scripting PrimeAgent operations.

### Detach/Reattach Workflow

Because the session worker runs as a separate process from the client, you can detach and reattach to running sessions:

```bash
prime-agent agents          # list running sessions with IDs

prime-agent attach <id>    # re-attach to a specific background session

prime-agent --resume       # continue the most recent session

```

This architecture enables long-running autonomous tasks that survive terminal closures and system sleep/wake cycles.

## Project-Specific Configuration

PrimeAgent reads custom behavior instructions from an [`AGENTS.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/AGENTS.md) file in your project root. Create this file to define:

- Project-specific coding conventions
- Preferred tool usage patterns
- Context about your codebase structure

The daemon checks for [`AGENTS.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/AGENTS.md) on session startup and incorporates its contents into the system prompt.

## Key Configuration Files Reference

| File | Purpose |
|------|---------|
| [`README.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/README.md) | High-level description and quick install commands |
| [`packages/coding-agent/docs/quickstart.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/quickstart.md) | Step-by-step first session instructions |
| [`packages/coding-agent/docs/architecture.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/architecture.md) | Component diagrams and execution flow details |
| [`prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/prime-agent.sh) | Source tree launcher script |
| [`packages/coding-agent/docs/providers.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/providers.md) | Provider credentials and environment variables |
| [`AGENTS.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/AGENTS.md) | Project-specific instruction file (user-created) |

## Summary

- **Two installation paths**: Pre-built release via install script, or source build with Node 22+ and `npm ci`
- **Authentication options**: Interactive `/login` command or environment variable API keys (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.)
- **Modular architecture**: Client, daemon, and worker processes enable detach/reattach and background task persistence
- **Session storage**: JSONL files in `~/.prime/agent/sessions/` preserve transcript history and generated artifacts
- **Project customization**: Create [`AGENTS.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/AGENTS.md) in project roots to tailor behavior to your codebase

## Frequently Asked Questions

### What are the system requirements for running PrimeAgent locally?

PrimeAgent requires macOS or Linux for the pre-built release, or Node 22+ for source builds. The daemon and worker processes consume moderate memory; 4GB RAM is sufficient for most coding tasks. No GPU is required as inference runs against remote model providers.

### How do I switch between different model providers?

Use the `/login` command in an interactive session to reauthenticate with a different provider, or set the corresponding environment variable (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GROQ_API_KEY`, etc.) before launching. The active provider is determined at session startup and persists for that session's lifetime.

### Can I run PrimeAgent without the interactive TUI?

Yes. Use the `prime-agent -p "your prompt"` syntax for headless execution. This returns results to stdout and exits, making it suitable for scripts and automation. File context can be attached with `@path/to/file` syntax.

### Where are my session histories stored if I want to back them up or delete them?

All session data lives in `~/.prime/agent/sessions/` as JSONL files. Each session has its own subdirectory containing transcript events, generated artifacts, and kernel state. Delete specific session directories to remove history, or back up the entire folder to preserve your work across machines.