Environment Variables

This page is the per-variable reference. For the convention (how to add a new env var, the loader, the checklist), see Getting Started → Environment Variables. The canonical template with blank values lives at .env.example at the repo root.

Conventions used in the tables

Variables with safety-critical behavior have an extra prose note directly below their table.

Precedence

Variables exported by your shell, CI, or systemd win over values in .env. The loader does not overwrite existing keys. See loader details.

LLM providers

At least one LLM path must resolve at boot: ANTHROPIC_API_KEY, OPENROUTER_API_KEY, or a stored OAuth profile from minara login openai | anthropic | openrouter. If none resolve, the process refuses to start with NoProviderAvailableError.

Minara core

HTTP gateway

Only matters for npm run serve / node dist/gateway/server.js.

⚠ Never expose an unauthenticated gateway to the internet. Fund-moving tools are reachable through /v1/chat. Set GATEWAY_AUTH_TOKEN to a high-entropy value (e.g. openssl rand -hex 32) before binding to any non-loopback interface. See HTTP API → Authentication.

Safety and fund-moving

⚠ MINARA_SKIP_FUND_CONFIRM is the only process-wide bypass of the handler-level confirmation gate. The LLM cannot skip it; the REPL cannot skip it. Use it only in non-interactive contexts (backtests, server-side workflow engine, CI smoke tests). Never set it in an interactive REPL session or on a production deployment unless you are certain every caller is non-human.

Builtin tools

Each entry gates one or more tool factories or skills. Missing var means the tool factory returns [] and the gated skill is hidden from the catalog. See Adding a Tool → feature-gating on env.

TWITTERAPI_API_KEY and X_API_BEARER_TOKEN are distinct. The former goes through a third-party scraper; the latter speaks directly to api.x.com/2. Either or both can be set.

E2B cloud sandbox

E2B is opt-in. The local code/shell sandbox remains the default even when E2B is configured. The router only hands work to workspace.e2b when the user names it explicitly ("e2b", "cloud sandbox", "isolated VM"), unless FORCE_E2B=1 flips the contract.

Autonomous turns (cron, workflow, price-alert) cannot auto-activate workspace.e2b without an operator-authored workflow that explicitly declares it in skill_scope. The workflow engine's trustedSeed path emits a loud audit log whenever that escape is exercised. See Workflows.

MCP integrations

See MCP Integration for the runtime semantics. All entries below are independently gated; missing envs don't break anything else.

All URL vars must advertise the streamable-HTTP MCP transport. The v1 SSE endpoints will not work.

External skills

Vendored skills under apps/agent/src/skills/external/ consume these through requires_env gating or by having the LLM read them via the terminal tool. Missing var means the corresponding skill is hidden from the catalog.

⚠ PRIVATE_KEY is a hot wallet key. Treat the machine that holds it as a trading terminal. Never put it in a shared or multi-user environment. Prefer hardware-wallet-backed signing where possible.

The three POLY_BUILDER_* variables must be set together. Partial configuration leaves the Polymarket skill in a half-configured state that fails on first authenticated call.

Reading the inventory programmatically

# Which env vars are set right now?
minara config list

# Which env-gated skills and tools are currently available?
minara skills list
minara tools list

# Full doctor report with env coverage
minara doctor

minara doctor is the fastest way to see which provider, tools, and skills are actually live given the env you've loaded. Missing credentials surface as yellow warnings rather than silent gaps.

Changes to this page

Adding or removing an env var requires updating all four locations in the same commit:

1. .env.example at the repo root.
2. apps/agent/docs-src/env-vars.md, the authoritative internal reference.
3. This page.
4. Getting Started → Environment Variables inventory table.

Reviewers reject PRs that touch process.env.<NAME> without matching doc updates. The convention is recorded in Conventions §1.