# Installation

> Stable install command, release checksum flow, prime-agent binary placement, IPython runtime prep, and first-launch success signals.

- Repository: PrimeIntellect-ai/prime-agent
- GitHub: https://github.com/PrimeIntellect-ai/prime-agent
- Human docs: https://grok-wiki.com/public/docs/primeintellect-ai-prime-agent-3367c32760b1
- Complete Markdown: https://grok-wiki.com/public/docs/primeintellect-ai-prime-agent-3367c32760b1/llms-full.txt

## Source Files

- `README.md`
- `package.json`
- `packages/coding-agent/README.md`
- `packages/coding-agent/test/suite/regressions/4537-nonblocking-onboarding.test.ts`
- `packages/coding-agent/test/suite/regressions/4573-prime-inference-login-default.test.ts`

---

---
title: "Installation"
description: "Stable install command, release checksum flow, prime-agent binary placement, IPython runtime prep, and first-launch success signals."
---

Prime Agent ships as **versioned tarball releases** installed by `https://app.primeintellect.ai/prime-agent/install.sh`. The installer downloads a release artifact, verifies its **SHA-256** checksum, places the public `prime-agent` command on your machine, and can prepare the **IPython** runtime the agent uses as its default control tool. Public packaging rewrites the application package and command name to `prime-agent`; do not install the inherited `@earendil-works/pi-*` / source-package `pi` bin as the product install path.

## Prerequisites

| Requirement | Detail |
|-------------|--------|
| Platform for install script | **macOS** or **Linux** (documented stable install path) |
| Working directory | Launch from the project directory the agent should operate in |
| Auth (first interactive use) | Subscription via `/login`, or an API key in the environment |
| Python kernel (optional override) | Existing environment with `ipykernel` via `PRIME_AGENT_KERNEL_PYTHON` |

<Warning>
Prime Agent runs model-generated Python and project commands with **your user permissions**. Worker and kernel processes improve lifecycle isolation and recovery; they are **not** a security sandbox. Use trusted repositories, instructions, skills, and extensions only. Run untrusted work in an external sandbox or restricted environment.
</Warning>

## Stable install

Install the latest stable release:

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

### What the installer does

| Step | Behavior |
|------|----------|
| Fetch | Downloads a **versioned** release tarball artifact |
| Verify | Checks the artifact **SHA-256** checksum |
| Install | Installs the public `prime-agent` command |
| Runtime | Can prepare the **IPython** runtime used by the agent |

Release packaging rewrites the application package and CLI entry to `prime-agent`. Treat the curl installer (or `prime-agent update`) as the supported end-user path—not the monorepo’s inherited npm/`pi` identifiers.

### Beta install

Install the beta built from the latest commit on `main`:

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

## `prime-agent` command placement

After a successful install, the public binary name is **`prime-agent`**. Confirm it resolves on `PATH`:

```bash
command -v prime-agent
prime-agent
```

| Surface | Role |
|---------|------|
| `prime-agent` | Public CLI entry after release packaging |
| Inherited `pi` / `@earendil-works/pi-*` | Source-workspace compatibility only—**not** the product install path |

### Update and lifecycle commands

```bash
prime-agent update [--force]         # Update Prime Agent
prime-agent status                   # Inspect background service state
prime-agent doctor [--fix]           # Inspect or repair background services
prime-agent shutdown [--force]       # Stop every agent, worker, and background service
```

Session and attach helpers available after install:

```bash
prime-agent agents                   # Browse running, idle, and saved sessions
prime-agent attach <agent>           # Reattach to a running session
prime-agent --resume <path|id>       # Resume a saved session
```

## IPython runtime prep

By default the model has one tool: **`ipython`**. The model uses a persistent kernel to read files, run commands, edit code, and inspect data.

| Behavior | Detail |
|----------|--------|
| Automatic setup | Python kernel runtime is set up **automatically on first invocation** |
| Installer assist | Install script **can prepare** the IPython runtime during install |
| Override | Set `PRIME_AGENT_KERNEL_PYTHON` to an existing Python environment that has **`ipykernel`** |

```bash
# Optional: point the kernel at a pre-provisioned Python with ipykernel
export PRIME_AGENT_KERNEL_PYTHON=/path/to/python
prime-agent
```

Capabilities beyond the default kernel (skills, prompt templates, extensions, packages) are added after install; they are not required for the install step itself.

## First launch

<Steps>
  <Step title="Install stable or beta">
    Run the stable or beta install command above, then confirm `prime-agent` is on `PATH`.
  </Step>
  <Step title="Enter the target project directory">
    Prime Agent works in the **current directory** and can run commands and modify files there. Prefer a disposable clone, clean worktree, or other checkpoint you can inspect and restore.

    ```bash
    cd /path/to/project
    prime-agent
    ```
  </Step>
  <Step title="Authenticate">
    **Subscription / OAuth**

    ```bash
    prime-agent
    /login   # Select provider
    ```

    **API key (example: Anthropic)**

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

    Built-in providers include subscription paths (Anthropic Claude Pro/Max, OpenAI ChatGPT Plus/Pro Codex, GitHub Copilot) and many API-key providers (Anthropic, OpenAI, Prime Inference, Azure OpenAI, and others). Custom providers can be registered under `~/.prime/agent/models.json` when they speak a supported API (OpenAI, Anthropic, Google).
  </Step>
  <Step title="Select a model if needed">
    Use `/model` or **Ctrl+L** after authentication. Built-in tool-capable model lists are maintained per provider and updated with each release.
  </Step>
</Steps>

### Auth persistence after login

After a successful provider login, the interactive flow **refreshes** available models, **selects** the provider default, and **persists** settings so the next process starts with a valid model. For Prime Inference (`api_key`), that default is **GLM 5.2** (`PRIME_INFERENCE_DEFAULT_MODEL_ID`), with API base `https://api.pinference.ai/api/v1` in the connection model shape used by the runtime.

Order of operations after login success: **refresh → select → persist**.

### Onboarding behavior

Once onboarding has been shown (`onboardingShown: true` in settings), client-local auth mismatch or a missing daemon session model must **not** reopen onboarding. Treat a quiet re-entry (no forced onboarding loop) as expected when onboarding already completed.

## First-launch success signals

Use these checks after install:

| Signal | Expected |
|--------|----------|
| Binary resolves | `command -v prime-agent` prints a path; shell can execute `prime-agent` |
| Interactive UI | **Startup header** with compact brand and runtime summary; messages area; editor; footer (empty by default) |
| Verbose load list | `prime-agent --verbose` lists loaded AGENTS.md files, prompt templates, skills, and extensions |
| Auth | `/login` completes, or API key env is accepted; `/model` / Ctrl+L can switch models |
| Default tool | Session is usable with the built-in **`ipython`** tool |
| Kernel | First invocation completes kernel setup without requiring a manual install step (unless you override via `PRIME_AGENT_KERNEL_PYTHON`) |
| Defaults persisted | After login, default provider/model survive process restart (settings flush) |
| Onboarding | Already-shown onboarding does not reopen for client-local auth mismatch or missing model |
| Update path | `prime-agent update [--force]` is available for later upgrades |
| Services (optional) | `prime-agent status` / `prime-agent doctor` inspect background service state |

<Check>
Healthy first run: install succeeds, `prime-agent` launches in the project directory, auth or API key is configured, the startup header appears, and you can talk to the agent while it uses the IPython kernel.
</Check>

## Config and data locations (post-install)

| Path | Use |
|------|-----|
| `~/.prime/agent/models.json` | Custom providers and models (supported API shapes) |
| `~/.prime/agent/keybindings.json` | Custom keybindings |

Session settings (including default provider/model and `onboardingShown`) are managed by the agent settings layer and flushed so restarts keep valid defaults.

## Release and monorepo notes

For end users, install via the curl script above. The monorepo (`package.json` name `prime-agent`, version **0.7.0**, Node **`>=22.8.0`**) exposes packaging and installer checks used by maintainers:

| Script | Role |
|--------|------|
| `npm run check:installer` | `node scripts/check-installer-render.mjs` |
| `npm run release:pack` | `node scripts/pack-prime-agent-release.mjs` |
| `npm run release:patch` / `release:minor` / `release:major` | Release automation via `scripts/release.mjs` |

CI includes a **Build Binaries** workflow badge; public distribution remains the versioned tarball + install script path described above.

## Common failure probes

| Symptom | What to check |
|---------|----------------|
| `prime-agent` not found | Installer did not complete; shell `PATH` not refreshed; re-run stable install |
| Installer exits mid-download | Network to `app.primeintellect.ai`; re-run so SHA-256 verification can complete on a full artifact |
| Kernel / IPython errors | Let automatic first-invocation setup finish, or set `PRIME_AGENT_KERNEL_PYTHON` to a Python with `ipykernel` |
| Auth / empty model | Run `/login` or export a valid API key; confirm default provider/model after login (refresh → select → persist) |
| Unexpected onboarding again | Confirm `onboardingShown` already true; reopening for client-local auth mismatch or missing model is a regression |
| Stale install | `prime-agent update [--force]`; use beta only when you intentionally want `main` builds |
| Background services | `prime-agent doctor [--fix]`, `prime-agent status`, `prime-agent shutdown [--force]` |

## Related pages

<CardGroup>
  <Card title="Quickstart" href="/quickstart">
    Start in a project directory, complete onboarding, run a first task, and verify interactive session health.
  </Card>
  <Card title="Authentication and providers" href="/authentication-providers">
    Login and API-key paths, multi-provider selection, OAuth examples, and BYOK boundaries.
  </Card>
  <Card title="RLM control plane" href="/rlm-control-plane">
    Persistent IPython as the control tool, prompt-as-variable context, and `rlm(...)` subagent calls.
  </Card>
  <Card title="Settings and provider keys" href="/settings-providers">
    Provider registration, model selection, API key and OAuth wiring, and 401 recovery.
  </Card>
  <Card title="Troubleshooting" href="/troubleshooting">
    Auth failures, provider 401s, network retry, worker recovery, and connection-mode probes.
  </Card>
  <Card title="Develop from source" href="/develop-from-source">
    Monorepo workspaces, build and check scripts, package boundaries, and contributor conventions.
  </Card>
</CardGroup>