How to Configure Prime Agent: Environment Variables and Setup Guide

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 and API credentials managed in 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 serves as the primary entry point for configuration. Located in the repository root, this script automatically detects and loads a .env file if present:

#!/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:

./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, the application reads provider credentials directly from process.env:

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 (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:

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:

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:

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:

# .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:

./prime-agent.sh

Running with Explicit Variables

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

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:

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 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 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.
• 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 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) 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}