reference configuration

Configuration

Prime Agent is configured through four layers: environment variables, JSON settings files, a credentials store, and the compile-time toolchain config. This page documents each surface and where it lives in the repository.

Environment variables

Provider API keys

Provider credentials are resolved from environment variables in packages/ai/src/env-api-keys.ts (findEnvKeys and getEnvApiKey). For each provider, the reported key(s) are checked in order.

Provider	Environment variable(s)
Anthropic	ANTHROPIC_OAUTH_TOKEN, ANTHROPIC_API_KEY (OAuth token takes precedence)
GitHub Copilot	COPILOT_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKEN
OpenAI	OPENAI_API_KEY
Azure OpenAI (Responses)	AZURE_OPENAI_API_KEY
Prime Inference	PRIME_API_KEY
DeepSeek	DEEPSEEK_API_KEY
Google (Gemini)	GEMINI_API_KEY
Google Vertex AI	GOOGLE_CLOUD_API_KEY, or ambient Application Default Credentials with GOOGLE_APPLICATION_CREDENTIALS, GOOGLE_CLOUD_PROJECT/GCLOUD_PROJECT, GOOGLE_CLOUD_LOCATION
Groq	GROQ_API_KEY
Cerebras	CEREBRAS_API_KEY
xAI	XAI_API_KEY
OpenRouter	OPENROUTER_API_KEY
Vercel AI Gateway	AI_GATEWAY_API_KEY
Z.ai	ZAI_API_KEY
Mistral	MISTRAL_API_KEY
MiniMax (global / CN)	MINIMAX_API_KEY, MINIMAX_CN_API_KEY
Moonshot AI	MOONSHOT_API_KEY
Hugging Face	HF_TOKEN
Fireworks	FIREWORKS_API_KEY
Opencode	OPENCODE_API_KEY
Kimi Coding	KIMI_API_KEY
Cloudflare Workers AI / AI Gateway	CLOUDFLARE_API_KEY
Xiaomi (and token-plan regions)	XIAOMI_API_KEY, XIAOMI_TOKEN_PLAN_CN_API_KEY, XIAOMI_TOKEN_PLAN_AMS_API_KEY, XIAOMI_TOKEN_PLAN_SGP_API_KEY
Amazon Bedrock	Ambient credentials: AWS_PROFILE, or AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY, AWS_BEARER_TOKEN_BEDROCK, AWS_CONTAINER_CREDENTIALS_RELATIVE_URI / AWS_CONTAINER_CREDENTIALS_FULL_URI, AWS_WEB_IDENTITY_TOKEN_FILE
Prime team selection	PRIME_TEAM_ID (falls back to team_id in ~/.prime/config.json)

The key lookup deliberately excludes ambient credential sources such as AWS profiles and Google Application Default Credentials from the reported key list; those are resolved separately by getEnvApiKey.

Prime Agent runtime variables

These variables control the agent binary and are documented in packages/coding-agent/docs/settings.md and defined in packages/coding-agent/src/config.ts.

Variable	Purpose
PRIME_AGENT_KERNEL_PYTHON	Override the Python interpreter used to bootstrap the IPython kernel.
PRIME_AGENT_SESSION_DIR	Override the session storage directory (precedence: --session-dir, then this, then the legacy PRIME_AGENT_CODING_AGENT_SESSION_DIR, then sessionDir in settings).
PRIME_AGENT_CODING_AGENT_DIR	Override the agent config directory (default ~/.prime/agent).
PRIME_AGENT_TELEMETRY=0	Disable pseudonymous usage analytics (also DO_NOT_TRACK=1).
PRIME_AGENT_TELEMETRY_ENDPOINT	Override the analytics ingestion endpoint for self-hosted deployments.
PRIME_AGENT_DOWNLOAD_BASE_URL	Point self-update at an internal stable or beta release manifest.
PI_SKIP_VERSION_CHECK=1	Skip the version update check.
PI_OFFLINE=1	Disable startup network operations, including update and package checks.
PRIME_AGENT_INTERACTIVE_SELF_UPDATE	Internal marker for interactive self-update child processes (packages/coding-agent/src/config.ts).
PI_PACKAGE_DIR	Override the package asset directory (useful for Nix/Guix).
PI_SHARE_VIEWER_URL	Override the session share viewer base URL (default https://pi.dev/session/).
PI_CLEAR_ON_SHRINK, PI_FULLSCREEN, PI_HARDWARE_CURSOR	Terminal behavior overrides consulted by packages/coding-agent/src/core/settings-manager.ts.

Web build variables

Variable	Purpose
VITE_FLEET_PI_CHAT_RUNTIME_URL	Build-time Vite variable that points the browser at a remote chat runtime; consumed in web/app/src/lib/pi/chat-runtime-url.ts.

Settings manager

User preferences are stored as JSON settings files managed by SettingsManager in packages/coding-agent/src/core/settings-manager.ts. Project settings override global settings, and nested objects merge recursively. The file locations are defined in packages/coding-agent/docs/settings.md.

Location	Scope
~/.prime/agent/settings.json	Global (all projects)
.prime/agent/settings.json	Project (current working directory)

The settings file covers model and thinking defaults (defaultProvider, defaultModel, defaultThinkingLevel, thinkingBudgets), UI display (theme, quietStartup, treeFilterMode), compaction and branch summary budgets, retry policy, message delivery (steeringMode, followUpMode, transport), terminal and image behavior, shell and package-manager commands (shellPath, shellCommandPrefix, npmCommand), daemon idle eviction, session directory, model cycling patterns, markdown indentation, and resource sources (packages, extensions, skills, prompts, themes).

Resource paths in the global file resolve relative to ~/.prime/agent; paths in the project file resolve relative to .prime/agent. Telemetry can be disabled per project but project settings can only further restrict the global opt-out.

Credential storage (auth.json)

API keys and OAuth tokens are stored per provider in ~/.prime/agent/auth.json, managed by AuthStorage in packages/coding-agent/src/core/auth-storage.ts. The file is created with 0600 permissions and the parent directory with 0700. Writes use file locking (proper-lockfile) to serialize concurrent token refreshes.

Each provider entry is either { "type": "api_key", "key": ... } or { "type": "oauth", ... } with OAuth access/refresh fields. Key resolution priority is: runtime override (--api-key), then Prime Inference environment/CLI config, then stored credentials, then environment variables, then a fallback resolver for custom models.json providers. For providers other than Prime Inference, stored auth.json credentials take precedence over environment variables.

Config constants

packages/coding-agent/src/config.ts derives app identity from the package manifest:

• APP_NAME, prime-agent (from piConfig.name in packages/coding-agent/package.json).
• CONFIG_DIR_NAME, .prime/agent, the per-project config directory (from piConfig.configDir).
• VERSION, the lockstep package version (0.7.1).
• getAgentDir(), ~/.prime/agent by default, overridable via PRIME_AGENT_CODING_AGENT_DIR.

getAgentDir() is the parent for settings.json, auth.json, models.json, sessions/, logs/, prompts/, tools/, bin/, and cron-jobs.json.

Toolchain config

The build, lint, and dependency constraints live in root-level files:

• .npmrc, sets min-release-age=7 so npm never resolves a package published less than 7 days ago (requires npm >= 11.10).
• web/pnpm-workspace.yaml, sets minimumReleaseAge: 10080 (7 days in minutes) to match, plus link: overrides that keep the in-tree @earendil-works/* packages on the web workspace.
• biome.json, lint and format rules (npm run check runs biome check --write --error-on-warnings .); tab indentation, 120-column width, selected rules turned off.
• tsconfig.base.json, shared strict TypeScript compiler options (target ES2022, Node16 module resolution).
• doctor.config.jsonc, React Doctor configuration recording scoped rule waivers and intentional-exception justifications for the web stack.