This page lists every environment variable that rpi reads from source. Values
are never documented here; set them in your shell or agent configuration. The
lists are grouped by function rather than priority.
Variable Default Purpose
PI_HOMEAuto-detected from the running executable layout Binary install root used by the self-updater PI_UPDATE_BASE_URLhttps://api.github.com/repos/0x8f701/rpi/releasesRelease API endpoint for update checks and self-update GITHUB_TOKEN(none) Authenticate GitHub API calls when the updater hits api.github.com PI_OFFLINE(none) Disables updater networking, llama.cpp router refresh, and other non-essential network calls when set to 1, true, or yes PI_SKIP_VERSION_CHECK(none) Disables only the nonfatal interactive startup version check when set
Variable Default Purpose
PI_CODING_AGENT_DIRDefault agent directory under the user's home Agent config directory (models.json, auth.json, resources, llama cache) SESSIONS_HOME$HOMERelocates the native session subtree to $SESSIONS_HOME/.pi/agent/sessions (with the same ~ expansion and absolute-path handling as the catalog) PI_PACKAGE_DIR(none) Overrides upstream-style package/docs path discovery PI_SHARE_VIEWER_URL(none) Viewer URL template for shared sessions; {url} substitutes the gist URL
PI_CODING_AGENT_DIR is the only way to relocate the agent tree; the current
working directory is never trusted as a fallback. SESSIONS_HOME relocates
only the session subtree — agent configuration, skills, and resources remain
under PI_CODING_AGENT_DIR (or $HOME) when only SESSIONS_HOME is set.
Precedence for the session store root is PI_CODING_AGENT_DIR >
$SESSIONS_HOME/.pi/agent > $HOME/.pi/agent.
Variable Purpose
LLAMA_BASE_URLllama.cpp router base URL (without /v1) LLAMA_API_KEYOptional llama.cpp router bearer token HF_TOKENHugging Face token for GGUF search/download HF_TOKEN_PATHPath to a file containing a Hugging Face token HF_HOMEHugging Face cache home; token is read from token inside it HF_ENDPOINTOverride the Hugging Face base URL XDG_CACHE_HOMECache home; token is read from huggingface/token inside it HOME / USERPROFILEUser home directory; used for cache and agent directory fallbacks
The bash tool receives the parent process environment with these additions:
Variable Purpose
PI_PROVIDERResolved provider id PI_MODELResolved model id PI_REASONING_LEVELCurrent thinking level name PI_SESSION_IDCurrent session id PI_SESSION_FILEPath to the current session file
Parent-process values for these keys are stripped before the additions are
applied, so stale values never leak into a child.
These variables are read by rpi to authenticate provider requests. Empty values
are treated as unset.
Variable(s) Provider
ANTHROPIC_API_KEY, ANTHROPIC_OAUTH_TOKEN, ANTHROPIC_AUTH_TOKENAnthropic COPILOT_GITHUB_TOKENGitHub Copilot OPENAI_API_KEYOpenAI, OpenAI Codex AZURE_OPENAI_API_KEYAzure OpenAI Responses GEMINI_API_KEYGoogle Gemini GOOGLE_CLOUD_API_KEYGoogle Vertex (API-key auth) GOOGLE_CLOUD_ACCESS_TOKENGoogle Vertex (access-token auth) GROQ_API_KEYGroq CEREBRAS_API_KEYCerebras XAI_API_KEYxAI DEEPSEEK_API_KEYDeepSeek OPENROUTER_API_KEYOpenRouter NVIDIA_API_KEYNVIDIA MISTRAL_API_KEYMistral MINIMAX_API_KEY, MINIMAX_CN_API_KEYMiniMax MOONSHOT_API_KEYMoonshot HF_TOKENHugging Face FIREWORKS_API_KEYFireworks TOGETHER_API_KEYTogether OPENCODE_API_KEYOpenCode KIMI_API_KEYKimi coding CLOUDFLARE_API_KEYCloudflare Workers AI / AI Gateway AWS_PROFILEAmazon Bedrock AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEYAmazon Bedrock (SigV4) AWS_SESSION_TOKENAmazon Bedrock session token AWS_BEARER_TOKEN_BEDROCKAmazon Bedrock bearer auth AWS_CONTAINER_CREDENTIALS_RELATIVE_URIAmazon Bedrock container credentials AWS_CONTAINER_CREDENTIALS_FULL_URIAmazon Bedrock container credentials AWS_WEB_IDENTITY_TOKEN_FILEAmazon Bedrock web-identity credentials ANT_LING_API_KEYAnt Ling QWEN_TOKEN_PLAN_API_KEY, QWEN_TOKEN_PLAN_CN_API_KEYQwen token-plan ZAI_API_KEY, ZAI_CODING_CN_API_KEYZAI XIAOMI_API_KEY, XIAOMI_TOKEN_PLAN_CN_API_KEY, XIAOMI_TOKEN_PLAN_AMS_API_KEY, XIAOMI_TOKEN_PLAN_SGP_API_KEYXiaomi RADIUS_API_KEYRadius AI_GATEWAY_API_KEYVercel AI Gateway
Precedence notes:
Anthropic : ANTHROPIC_OAUTH_TOKEN wins over ANTHROPIC_API_KEY. ANTHROPIC_AUTH_TOKEN is used as a bearer header and is never returned as an API key.Amazon Bedrock : ambient AWS credentials (shared config files, instance metadata, etc.) are intentionally not read. Only the listed environment variables are considered.Google Vertex : ADC files and credential helpers are not read. Use GOOGLE_CLOUD_API_KEY, GOOGLE_CLOUD_ACCESS_TOKEN, or an authorization header.
In addition to AZURE_OPENAI_API_KEY:
Variable Purpose
AZURE_OPENAI_API_VERSIONAPI version, default v1 AZURE_OPENAI_BASE_URLBase URL override AZURE_OPENAI_RESOURCE_NAMEResource name; builds https://{name}.openai.azure.com/openai/v1 AZURE_OPENAI_DEPLOYMENT_NAME_MAPComma-separated modelId=deploymentName mappings
Variable Purpose
AWS_REGIONBedrock region AWS_DEFAULT_REGIONFallback region AWS_BEDROCK_SKIP_AUTHSet to 1 to skip auth (test/local only) AWS_BEDROCK_FORCE_CACHESet to 1 to force prompt caching
See the provider API-keys table above for the credential variables.
Variable Purpose
GOOGLE_CLOUD_PROJECTRequired project id (alias GCLOUD_PROJECT) GOOGLE_CLOUD_LOCATIONRequired location GOOGLE_CLOUD_ACCESS_TOKENShort-lived access token GOOGLE_CLOUD_API_KEYAPI key (sent as x-goog-api-key)
Variable Purpose
PI_CACHE_RETENTIONSet to long to request 24h prompt-cache retention for Anthropic and OpenAI Responses models
For Cloudflare Workers AI and AI Gateway models.json baseUrl values may
contain:
{CLOUDFLARE_ACCOUNT_ID} — from env CLOUDFLARE_ACCOUNT_ID
{CLOUDFLARE_GATEWAY_ID} — from env CLOUDFLARE_GATEWAY_ID
They are replaced at request time before the URL is used. If a placeholder is
present and the matching variable is unset, the request fails.
Variable Purpose
PI_OAUTH_CALLBACK_HOSTOverride the OAuth redirect callback bind address (default 127.0.0.1) KIMI_CODE_OAUTH_HOSTOverride the Kimi Code OAuth host KIMI_OAUTH_HOSTFallback override for the Kimi OAuth host
Variable Purpose
PI_EXTENSION_IDExtension id passed to extensions (internal) PI_EXTENSION_ENTRYExtension entry path (internal) PI_EXTENSION_PACKAGE_IDPackage id for the extension (internal) PI_EXTENSION_CAPABILITIESJSON capabilities list (internal) PI_EXTENSION_UI_CAPABILITIESJSON UI capabilities list (internal) PI_EXTENSION_MAX_FRAME_BYTESMax extension IPC frame size (internal) PI_EXTENSION_PROTOCOL_VERSIONExtension protocol version (internal)
Variable Purpose
CODEX_HOMECodex directory under the user's home; session import source CLAUDE_CONFIG_DIRClaude config directory under the user's home; project import source
Variable Purpose
VISUALPreferred external editor EDITORFallback external editor DISPLAYX11 display detection for clipboard WAYLAND_DISPLAYWayland display detection XDG_SESSION_TYPESession type detection (e.g. wayland) COLORFGBGTerminal background-color hint for theme selection XDG_CONFIG_HOMEUsed to locate git/ignore and other config fallbacks
auth.json and models.json values may use these forms:
Form Meaning
$VARExpand a single variable from the process environment ${VAR}Explicit boundary $$Literal $ $!Literal !
For auth.json credentials, variables are also resolved from the optional
per-credential env map. models.json values use only the process
environment (and, for OAuth-stored credentials, the credential's own env).
Unset variables produce an error; there is no default-value syntax.
Command-valued values (!command) are rejected for API keys and headers.