# How to Train or Fine‑Tune PrimeAgent Models: A Complete CLI Workflow

> Learn to train or fine-tune PrimeAgent models with the Prime CLI and Continual Harness. This guide details the essential commands for a streamlined GPU-backed workflow.

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

---

**You train or fine‑tune PrimeAgent models using the `prime` CLI and the Continual Harness machinery, which orchestrates environment setup, configuration generation, and GPU‑backed execution through three commands: `prime train init`, `prime train rl.toml`, and `prime harness apply`.**

PrimeAgent provides a unified, code‑first approach to reinforcement learning (RL) training and fine‑tuning. Whether you are adapting a base model to a custom verification environment or applying parameter‑efficient updates to an existing checkpoint, the workflow is driven entirely by configuration files and CLI commands. This guide walks through the exact steps implemented in the `prime-intellect/prime-agent` repository, referencing the source files that define the training system.

## Prepare Your Training Environment

Every training run in PrimeAgent targets a **verification environment**—a task suite that provides rewards, unit tests, or human feedback signals. Before invoking training, you must ensure your environment is discoverable by the `verifiers` package.

PrimeAgent environments are documented in [`packages/coding-agent/skills/prime-intellect/references/environments.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/skills/prime-intellect/references/environments.md), which defines how the `prime train` commands interact with environment loaders【/packages/coding-agent/skills/prime-intellect/references/environments.md#L59-L65】.

Register and inspect environments using the CLI:

```bash

# List environments already available to the agent

prime env list

# Register a new environment from a local directory

prime env add my-custom-env

```

Environments are stored under `~/.prime/agent/environments`. Each must expose a standard interface that the **Hosted Training** service can invoke during rollout collection.

## Generate a Training Configuration with `prime train init`

The `prime train init` command bootstraps a reproducible training run by generating an [`rl.toml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/rl.toml) file. This file encodes:

- The **target model** (e.g., `openai/gpt-4o`, `anthropic/claude-3-opus-20240229`)
- **Hyperparameters**: learning rate, batch size, total steps, and checkpoint frequency
- **Environment reference**: which verification suite to use for reward computation

Run the initializer:

```bash
prime train init --model openai/gpt-4o --env my-custom-env

```

This creates [`rl.toml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/rl.toml) in your working directory. You can edit this file directly to adjust training depth, enable **LoRA adapters**, or switch gradient accumulation strategies.

## Launch Training and Persist to the Continual Harness

Execute the training run by passing your configuration to the `prime train` command:

```bash
prime train rl.toml

```

The CLI submits the job to the Prime Intellect training backend, which provisions a temporary GPU pod, executes the RL loop, and streams logs to your terminal. Upon completion, the **Continual Harness** automatically records:

- Model version and architecture fingerprint
- Full hyperparameter snapshot
- Training data hashes and evaluation metrics
- Reproducibility artifacts (seeds, dependency versions)

This trace is stored in your session directory and can be listed or reapplied without re-running the full experiment.

Inspect and refine harness entries:

```bash

# Display all stored training traces with metadata

prime harness show

# Apply a refinement (additional fine-tuning) from a previous run

prime harness apply <trace-id>

```

The harness architecture ensures that iterative improvements—common in RL fine-tuning—are tracked and reversible.

## Fine‑Tune Existing Models

Fine‑tuning follows the identical three-stage workflow. In your [`rl.toml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/rl.toml), specify a base model identifier and constrain which parameters to update:

- **Full fine‑tuning**: Update all weights (higher compute cost)
- **Adapter-based fine‑tuning**: Train LoRA or similar adapters on target layers only

After the run completes, the resulting adapter is stored in harness format and exposed through the `inference/adapter-deployments` API. Load it programmatically:

```typescript
import { getAvailableModels } from "@mariozechner/pi-ai";

const models = await getAvailableModels();
const fineTuned = models.find(m => m.id === "openai/gpt-4o-adapter-my-run");

if (fineTuned) {
  console.log("Adapter ready for inference:", fineTuned.id);
}

```

## Key Source Files and Their Roles

| File | Purpose |
|------|---------|
| [`packages/coding-agent/skills/prime-intellect/references/environments.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/skills/prime-intellect/references/environments.md) | Documents `prime train` commands, [`rl.toml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/rl.toml) schema, and Hosted Training integration【/packages/coding-agent/skills/prime-intellect/references/environments.md#L59-L65】 |
| [`packages/coding-agent/src/core/system-prompt.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/system-prompt.ts) | Injects training‑specific instructions into the LLM system prompt, directing queries to README.md for authoritative command references【/packages/coding-agent/src/core/system-prompt.ts#L126-L131】 |
| [`packages/coding-agent/src/utils/config.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/utils/config.ts) | Provides `getReadmePath()` and `getChangelogPath()` helpers used by the system prompt to locate documentation【/packages/coding-agent/src/utils/config.ts#L425-L427】 |
| [`packages/ai/src/types.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/types.ts) | Defines `DataCollectionSetting` (`allow`/`deny`) controlling whether providers may retain or train on user data【/packages/ai/src/types.ts#L363-L365】 |
| [`packages/ai/README.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/README.md) | Catalogs supported providers and model capabilities for selecting fine‑tuning base models【/packages/ai/README.md#L8-L16】 |

## Summary

- PrimeAgent training is **CLI‑driven** through `prime train init` and `prime train rl.toml`, with configuration stored in [`rl.toml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/rl.toml) files.
- The **Continual Harness** automatically versions every run, enabling traceable refinements via `prime harness apply`.
- **Fine‑tuning** uses the same workflow as full RL training; adapters are stored and loaded through the standard inference API.
- Environment compatibility is verified through the `verifiers` package, documented in [`environments.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/environments.md)【/packages/coding-agent/skills/prime-intellect/references/environments.md#L59-L65】.
- The system prompt explicitly routes training queries to README.md, ensuring accurate, version‑matched guidance【/packages/coding-agent/src/core/system-prompt.ts#L126-L131】.

## Frequently Asked Questions

### What hardware does PrimeAgent use for training runs?

Training runs execute on temporary GPU pods provisioned by the Prime Intellect training backend. You do not manage infrastructure directly; the `prime train` command handles pod allocation, execution, and teardown automatically.

### Can I fine‑tune on private data without it being retained?

Yes. The `DataCollectionSetting` in [`packages/ai/src/types.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/types.ts)【/packages/ai/src/types.ts#L363-L365】 allows you to specify `deny`, which instructs providers not to store or train on your data. Verify this setting in your provider configuration before launching sensitive fine‑tuning jobs.

### How do I resume or extend a previous training run?

Use `prime harness show` to locate the trace ID of your prior run, then invoke `prime harness apply <trace-id>`. This loads the saved configuration and state, allowing refinements without restarting from scratch.

### Where can I find the exact command syntax for my PrimeAgent version?

The system prompt in [`packages/coding-agent/src/core/system-prompt.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/system-prompt.ts)【/packages/coding-agent/src/core/system-prompt.ts#L126-L131】 explicitly directs the LLM to consult [`README.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/README.md) for training queries. Run `prime --help` or check the README path returned by `getReadmePath()` in [`packages/coding-agent/src/utils/config.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/utils/config.ts)【/packages/coding-agent/src/utils/config.ts#L425-L427】 for version‑specific documentation.