# How to Configure Prime Agent: Environment Variables and Setup Guide

> Configure Prime Agent easily using environment variables. Learn how to set up your PrimeIntellect-ai/prime-agent with our comprehensive guide for seamless integration and optimal performance.

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

---

**Prime Agent is configured entirely through environment variables loaded from a `.env` file or passed directly to the shell, with core settings defined in [`packages/coding-agent/src/config.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/config.ts) and API credentials managed in [`packages/ai/src/env-api-keys.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/env-api-keys.ts).**

Prime Agent is an AI-powered coding system developed by PrimeIntellect-ai. To configure Prime Agent effectively, you must understand its hierarchical configuration model that relies on environment variables for everything from LLM API keys to daemon worker coordination and session management.

## Environment Variable Loading Flow

Prime Agent uses a cascading configuration system where variables flow from the shell through a bootstrap script into the Node.js runtime.

### The prime-agent.sh Entry Point

The launcher script [`prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/prime-agent.sh) serves as the primary entry point for configuration. Located in the repository root, this script automatically detects and loads a `.env` file if present:

```bash
#!/usr/bin/env bash

NO_ENV=false
if [ "$1" == "--no-env" ]; then
  NO_ENV=true
fi

if [ "$NO_ENV" == "true" ]; then
  echo "Skipping .env loading"
else
  if [ -f .env ]; then
    export $(cat .env | xargs)
  fi
fi

node ./dist/main.js "$@"

```

As implemented in the PrimeIntellect-ai/prime-agent repository, this script exports every `KEY=VALUE` line from the repository root's `.env` file into the process environment before starting the Node.js application.

### Skipping .env with --no-env

If you prefer to inject configuration via your shell, Docker secrets, or a CI pipeline, invoke the launcher with the `--no-env` flag:

```bash
./prime-agent.sh --no-env

```

This bypasses the automatic `.env` loader, allowing you to manage environment variables externally while still using the standard entry point.

## Required API Credentials

Prime Agent requires valid API keys for LLM providers to function. These credentials are exposed to the AI layer through a dedicated module.

### Provider Keys in env-api-keys.ts

According to the source code in [`packages/ai/src/env-api-keys.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/env-api-keys.ts), the application reads provider credentials directly from `process.env`:

```typescript
export const OPENAI_API_KEY = process.env.OPENAI_API_KEY;
export const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;

```

You must set these variables to enable the corresponding LLM backends. Without valid keys for at least one supported provider, the agent cannot execute AI-powered tasks.

## Core Configuration Constants

All canonical environment variable names are centralized in [`packages/coding-agent/src/config.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/config.ts) (version 0.3.1) to ensure consistency across the daemon system.

### Directory and Path Settings

The `ENV_AGENT_DIR` constant defines the variable name for the agent's working directory:

```typescript
export const ENV_AGENT_DIR = "PRIME_AGENT_DIR";
export const ORPHAN_PROCESS_JOURNAL_ENV = "PRIME_ORPHAN_PROCESS_JOURNAL";

```

When `PRIME_AGENT_DIR` is unset, the system typically falls back to `$HOME/.prime-agent` or an internal default defined alongside these constants.

### Daemon Worker Configuration

Prime Agent uses a sophisticated daemon system for process management. The following variables control worker behavior and inter-process communication:

```typescript
export const DAEMON_WORKER_ROLE_ENV = "PRIME_DAEMON_WORKER_ROLE";
export const DAEMON_WORKER_TOKEN_ENV = "PRIME_DAEMON_WORKER_TOKEN";
export const DAEMON_WORKER_SUPERVISOR_SOCKET_ENV = "PRIME_DAEMON_WORKER_SUPERVISOR_SOCKET";
export const DAEMON_WORKER_ACTIVE_SESSION_ID_ENV = "PRIME_DAEMON_WORKER_ACTIVE_SESSION_ID";
export const DAEMON_WORKER_RECOVERY_JOURNAL_ENV = "PRIME_DAEMON_WORKER_RECOVERY_JOURNAL";

```

These variables enable the daemon to locate resources, enforce session leases, and recover from crashes. Sub-processes inherit these values to maintain coordination across the worker hierarchy.

### Session Lease Management

For multi-session deployments,PrimeAgent supports lease-based session ownership:

```typescript
export const SESSION_LEASES_ENABLED_ENV = "PRIME_SESSION_LEASES_ENABLED";
export const SESSION_LEASE_OWNER_ID_ENV = "PRIME_SESSION_LEASE_OWNER_ID";

```

Set `PRIME_SESSION_LEASES_ENABLED` to activate lease enforcement, and use `PRIME_SESSION_LEASE_OWNER_ID` to identify the owning process or user.

## Practical Configuration Examples

### Basic .env Setup

Create a `.env` file in the repository root by copying `.env.example`:

```bash

# .env

OPENAI_API_KEY=sk-your-openai-key
ANTHROPIC_API_KEY=your-anthropic-key
PRIME_AGENT_DIR=$HOME/.prime-agent
PRIME_SESSION_LEASES_ENABLED=true

```

Then launch normally:

```bash
./prime-agent.sh

```

### Running with Explicit Variables

For containerized or CI environments, skip the `.env` file and export variables directly:

```bash
export OPENAI_API_KEY="sk-xxx"
export PRIME_AGENT_DIR="/app/data"
export PRIME_SESSION_LEASES_ENABLED="false"

./prime-agent.sh --no-env

```

### Accessing Configuration in Code

When extending Prime Agent, import the constant definitions to ensure you use the correct variable names:

```typescript
import { ENV_AGENT_DIR, DAEMON_WORKER_ROLE_ENV } from "./config.js";

const agentDir = process.env[ENV_AGENT_DIR] ?? "/default/path";
const workerRole = process.env[DAEMON_WORKER_ROLE_ENV] ?? "standard";

```

## Summary

- **Entry point**: The [`prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/prime-agent.sh) script loads `.env` automatically unless you pass `--no-env`.
- **API keys**: Set `OPENAI_API_KEY` and `ANTHROPIC_API_KEY` in [`packages/ai/src/env-api-keys.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/env-api-keys.ts) to authenticate with LLM providers.
- **Core constants**: All environment variable names (like `PRIME_AGENT_DIR` and `PRIME_DAEMON_WORKER_ROLE`) are defined centrally in [`packages/coding-agent/src/config.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/config.ts).
- **Daemon coordination**: Worker processes rely on `PRIME_DAEMON_WORKER_*` variables for socket communication, session tracking, and crash recovery.
- **Session leases**: Enable `PRIME_SESSION_LEASES_ENABLED` for deployment scenarios requiring exclusive session ownership.

## Frequently Asked Questions

### Where are API keys configured in Prime Agent?

API keys are configured via environment variables read from `process.env`. The file [`packages/ai/src/env-api-keys.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/env-api-keys.ts) exports `OPENAI_API_KEY` and `ANTHROPIC_API_KEY` by reading these variables. You should define them in a `.env` file or export them in your shell before starting the agent.

### Can I run Prime Agent without a .env file?

Yes. Launch the application using `./prime-agent.sh --no-env` to skip the automatic `.env` loader. This is useful for production deployments where you inject secrets via Kubernetes secrets, Docker environment variables, or other secure configuration management systems.

### What is the PRIME_AGENT_DIR variable used for?

`PRIME_AGENT_DIR` (defined as `ENV_AGENT_DIR` in [`packages/coding-agent/src/config.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/config.ts)) specifies the filesystem path where Prime Agent stores its state, journals, and working files. If unset, the application falls back to a default location typically located at `$HOME/.prime-agent`.

### How does Prime Agent handle daemon worker configuration?

Daemon workers use a set of `PRIME_DAEMON_WORKER_*` variables defined in [`config.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/config.ts) to coordinate execution. These include `PRIME_DAEMON_WORKER_ROLE` for role assignment, `PRIME_DAEMON_WORKER_TOKEN` for authentication, and `PRIME_DAEMON_WORKER_RECOVERY_JOURNAL` for crash recovery. These variables ensure sub-processes can communicate with their supervisor and resume operations after failures.