# How to Deploy Prime Agent (PrimeIntellect‑ai/prime‑agent): Complete Installation Guide

> Deploy Prime Agent with our complete installation guide. Learn the official installer script, run from source, or bundled distribution methods for seamless setup.

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

---

**Bold answer:** Prime Agent deploys via three methods: the **official installer script** for one‑step global installation, **run from source** for development, or the **bundled distribution** for containerized environments—each verified against SHA‑256 checksums with optional IPython runtime bootstrapping.

Prime Agent from PrimeIntellect‑ai is a self‑contained command‑line coding agent delivered as a TypeScript‑based TUI/CLI. Whether you need a quick production install or a development environment for hacking on the source, this guide covers every deployment path with references to the exact source files that implement each behavior.

---

## Deploy via the Official Installer

The **recommended path** for most macOS and Linux users is the signed release installer. It requires no source checkout and handles Node.js dependencies automatically.

### Run the Installer Script

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

```

The installer lives in [[`install.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/install.sh)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/install.sh). It performs these verified steps:

- **Pre‑flight checks** — verifies Node 20.6+ and `npm` are present (`run_preflight_checks` in [`install.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/install.sh) lines 96‑110)
- **Node installation** — auto‑installs Node via Homebrew, `apt`, `apk`, or standalone binary if missing (`install_node_standalone` etc., lines 126‑150)
- **Version resolution** — contacts the release channel (stable or beta) to obtain the latest version (`resolve_prime_agent_version`, lines 124‑148)
- **Download and verification** — fetches the tarball plus `SHA256SUMS`, then validates the checksum (`download_prime_agent_package` & `verify_prime_agent_package_checksum`, lines 54‑84)
- **Global npm install** — runs `npm install -g` on the verified tarball (`install_prime_agent_package`, lines 92‑102)
- **Optional IPython bootstrapping** — prompts to prepare the IPython runtime (`confirm_kernel_runtime_setup`, lines 55‑66)

### Add to PATH

If the installer cannot auto‑update your shell profile, it prints manual instructions (see `print_standalone_path_manual_instructions` in [`install.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/install.sh) lines 135‑140). Add the `export PATH="…:$PATH"` line from `standalone_node_path_line` to make `prime-agent` available in new shells.

### Launch

```bash
prime-agent

```

The command now points to the globally installed npm package, launching the TUI or CLI as documented in the README (lines 70‑78).

---

## Run Directly from Source

Use this method when modifying Prime Agent or running the bleeding‑edge `main` branch.

### Clone and Install Dependencies

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

```

**Node 22.8+ is required** for source execution.

### Launch with the Wrapper Script

```bash
./prime-agent.sh

```

The thin launcher script ([[`prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/prime-agent.sh)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/prime-agent.sh)) handles:

- Parsing `--no-env` and `--dist` flags
- Unsetting all API‑key environment variables when `--no-env` is used
- Executing either the bundled [`cli.js`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/cli.js) (`--dist`) or running source [`cli.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/cli.ts) via `tsx` (`node_modules/.bin/tsx`)

### Use the Bundled Distribution

```bash
./prime-agent.sh --dist

```

This skips the `tsx` interpreter and runs the pre‑built bundle from [`packages/coding-agent/dist/bundle/cli.js`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/dist/bundle/cli.js) (referenced at line 66 in [`prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/prime-agent.sh), lines 65‑73). The bundled mode provides approximately **3× faster startup** and is ideal for containers where `tsx` is undesirable.

---

## Post‑Installation Configuration

### Authentication

Run `/login` inside the TUI, or export an API key before launching:

```bash
export ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxx
prime-agent

```

Supported providers and environment variables are documented in the [Quickstart](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/quickstart.md) (lines 39‑64) and [providers documentation](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/providers.md).

### Project‑Specific Instructions

Add an [`AGENTS.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/AGENTS.md) or [`CLAUDE.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/CLAUDE.md) file in your project root to define custom policies. See the "Give Prime Agent Project Instructions" section of the Quickstart for format details.

### Session Management

Sessions auto‑save under `~/.prime/agent/sessions/`. Use:

- `prime-agent -c` — continue the most recent session
- `prime-agent agents` — list running workers

---

## Installation Method Comparison

| Method | Speed | Best For | Key File |
|--------|-------|----------|----------|
| **Official installer** | Fastest setup | Production macOS/Linux | [`install.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/install.sh) |
| **Source + tsx** | Moderate | Active development | [`prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/prime-agent.sh) (default) |
| **Source + `--dist`** | Fast | Containers, CI/CD | `prime-agent.sh --dist` |

---

## Code Reference: Key Implementation Files

| File | Purpose |
|------|---------|
| [`install.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/install.sh) | Downloads, verifies, and globally installs releases |
| [`prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/prime-agent.sh) | Runtime launcher selecting between `tsx` and bundled JS |
| [`packages/coding-agent/src/cli.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/cli.ts) | Main TypeScript entry point for interactive TUI/CLI |
| [`packages/coding-agent/docs/quickstart.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/quickstart.md) | First‑run guide and authentication steps |
| [`packages/coding-agent/docs/providers.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/providers.md) | LLM provider configuration reference |
| [`packages/coding-agent/docs/architecture.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/architecture.md) | Daemon/worker/kernel architecture deep‑dive |

---

## Summary

- **Official installer**: One‑line curl command with automatic Node.js handling, SHA‑256 verification, and optional IPython setup
- **Source execution**: Requires Node 22+, uses [`prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/prime-agent.sh) with `tsx` for development flexibility
- **Bundled mode**: Add `--dist` to [`prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/prime-agent.sh) for faster startup in containerized environments
- **Authentication**: Export provider API keys or use `/login` in the TUI
- **Configuration**: Use [`AGENTS.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/AGENTS.md) for project‑specific instructions and `~/.prime/agent/sessions/` for persistence

---

## Frequently Asked Questions

### What Node.js version does Prime Agent require?

The **official installer** requires Node 20.6+ and will auto‑install it if missing. Running **from source** requires Node 22.8+ as enforced by [`prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/prime-agent.sh). Check your version with `node --version` before attempting a source deployment.

### Is the official installer secure?

Yes. The installer in [`install.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/install.sh) downloads release tarballs over HTTPS, verifies their **SHA‑256 checksum** against a signed `SHA256SUMS` file (`verify_prime_agent_package_checksum`, lines 54‑84), and only proceeds with `npm install -g` after validation succeeds.

### Can I run Prime Agent without installing Node.js globally?

Yes. The official installer can bootstrap a **standalone Node binary** in a local directory (`install_node_standalone` in [`install.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/install.sh), lines 126‑150) and update your PATH accordingly. For containers, build once with `npm ci` and `npm run build`, then use `./prime-agent.sh --dist` to run the bundled JS without tsx.

### How do I switch between stable and beta releases?

Append `beta` to the installer command: `curl -fsSL https://app.primeintellect.ai/prime-agent/install.sh | sh -s -- beta`. The `resolve_prime_agent_version` function (lines 124‑148) detects the channel and fetches the corresponding release metadata.