Minara core

`MINARA_API_KEY`

Minara backend API credential.

What it controls: every call the agent makes into the Minara REST surface (portfolio, swap, perps, autopilot, workflow, analytics).
Consumed by: src/minara/client.ts, src/minara/read-client.ts, src/minara/safe-trading-client.ts via src/app.ts.
When to set: running in non-interactive contexts (CI, Docker, workflow engine) where a device-flow JWT is not available.
When unset: the gateway looks for a saved device-flow JWT at $MINARA_DATA_DIR/credentials.json (llm slot) (run minara auth login minara first). If neither exists the agent refuses Minara calls.
Format: opaque string issued by the Minara dashboard.
Setting home: Not a user-facing setting

`MINARA_BASE_URL`

Minara API base URL override.

What it controls: the origin every Minara HTTP client points at, including the OAuth /v1/oauth/authorize redirect target (which in turn hands the user to the same brand's consent page — point at a dev backend and the user sees the dev consent UI).
Consumed by: apps/agent/src/gateway/server.ts, apps/agent/src/gateway/auth-cli.ts, apps/agent/src/minara/client.ts, apps/agent/src/app.ts.
When to set: you're pointing at a self-hosted instance, a staging backend, or a local mock (see apps/agent/tests/fakes/mock-minara-server.ts).
When unset: defaults to the prod origin https://api.minara.ai (matches the CLI's DEFAULT_MINARA_BASE_URL constant).
Format: absolute URL, no trailing slash.
Setting home: Not a user-facing setting

`MINARA_FRONTEND_BASE_URL`

Minara web frontend base URL.

What it controls: the URL that token:// / address:// custom
URI schemes resolve to in terminal OSC 8 hyperlinks and deep-
research HTML reports, plus the desktop OAuth success page at
/oauth/desktop/success; it will also feed the upcoming
minara_open_pricing_page / _topup_page / _subscription_page tools.
Consumed by: apps/agent/src/config/frontend-url.ts (read by apps/agent/src/gateway/api.ts, apps/agent/src/gateway/render/uri-rewrite.ts and apps/agent/src/deep-research/report-renderer.ts).
When to set: shipping to prod (https://minara.ai) or running against a local Next.js dev server.
When unset: defaults to https://minara.ai.
Format: absolute URL, no trailing slash.
Setting home: Not a user-facing setting

`MINARA_DATA_DIR`

persistent state directory.

What it controls: where SQLite databases, the sandbox file jail, auth profiles, audit logs, and generated documents live.
Consumed by: apps/agent/src/gateway/cli.ts, apps/agent/src/app.ts, apps/agent/src/tools/_shared/sandbox.ts.
When to set: running under Docker / systemd where ~ maps to a non-persistent path, or you want to keep multiple agent profiles side-by-side.
When unset: defaults to ~/.minara.
Format: absolute filesystem path. Created on first boot if missing.
Setting home: Not a user-facing setting

`MINARA_TERMINAL_CWD`

agent working-directory override.

What it controls: the cwd the agent reads/writes user files in and runs shell commands from. Resolution order: per-session override (set by /cwd at runtime) → this var → process.cwd().
Consumed by: apps/agent/src/agent/runtime-cwd.ts (resolveAgentCwd).
When to set: gateway/cron entrypoints whose launch directory is the install directory, not the intended work directory. The local CLI usually leaves this unset and falls back to the shell cwd.
When unset: falls back to process.cwd() (the directory the agent process was launched from).
Format: absolute path to a real directory. A non-existent path is ignored and resolution falls through to process.cwd().
Setting home: Not a user-facing setting

`MINARA_BACKGROUND_MODELS_ENABLED`

MINARA_BACKGROUND_MODELS_ENABLED: default state for background task models.

What it controls: whether titles, compression, and unattended work use the models assigned in Settings. Chat keeps the selected model either way.
Consumed by: apps/agent/src/config/preferences/schema.ts and apps/agent/src/llm/model-routing-service.ts.
When to set: when an operator wants background task models on or off by default for a deployment. A saved user setting takes precedence.
When unset: defaults to enabled. The setting only takes effect while a Minara provider is active.
Format: boolean. Accepted true values: 1, true, yes, on. Accepted false values: 0, false, no, off.
Setting home: Settings → Preferences (schema key)

`MINARA_FINANCIAL_SAFETY_ENABLED`

MINARA_FINANCIAL_SAFETY_ENABLED: default state for financial safety reminders.

What it controls: whether the user-initiated Chat agent loop registers the financial safety skill for risky spending, trading escalation, scams, coercion, and personal-safety crisis signals. Background automations and subagents never receive it.
Consumed by: apps/agent/src/config/preferences/schema.ts, apps/agent/src/guardrail/service.ts, and apps/agent/src/app.ts.
When to set: set false when a deployment should start with financial safety disabled. A user choice saved in Personalization takes precedence.
When unset: defaults to enabled. Users can turn it off in Personalization → Financial safety.
Format: boolean. Accepted true values: 1, true, yes, on. Accepted false values: 0, false, no, off.
Setting home: Settings → Preferences (schema key)

`MINARA_AUTO_MODEL_STRATEGY`

MINARA_AUTO_MODEL_STRATEGY: default Auto chat mapping.

What it controls: how Auto maps a scored message onto fixed Minara catalog models. SIMPLE/MEDIUM use DeepSeek V4 Flash 0731 (Sonnet 5 when vision/PDF is required); economy COMPLEX uses GLM 5.2 and REASONING uses Kimi K3; balanced COMPLEX uses GPT-5.6 Terra and REASONING uses GPT-5.6 Sol; quality uses Sonnet 5 for SIMPLE/MEDIUM, GPT-5.6 Sol for COMPLEX, and Opus 5 for REASONING. Custom starts from these quality defaults. This does not change background task models.
Consumed by: apps/agent/src/config/preferences/schema.ts and apps/agent/src/llm/auto-model.ts.
When to set: when an operator wants Auto to lean cheaper or stronger by default. A saved user setting takes precedence. The row only appears after Auto is selected.
When unset: defaults to balanced.
Format: economy, balanced, quality, or custom. Custom starts from Quality and saves overrides in Settings.
Setting home: Settings → Preferences (schema key)

`MINARA_DEFAULT_MODEL`

initial agent model id.

What it controls: the default model id for interactive chat turns. When background task models are enabled, titles, compression, and unattended work may use the models assigned in Settings while chat keeps this id.
Consumed by: apps/agent/src/app.ts (createApp model-resolution chain).
When to set: when the persisted operator choice in the persisted model pin in ~/.minara/settings.json is wrong for the active provider — e.g. only OPENROUTER_API_KEY is configured but the persisted id is the Anthropic-native claude-sonnet-4-6, which OpenRouter rejects with a 400 (its naming is anthropic/claude-sonnet-4.5). The web UI's Settings → Model picker is the long-term answer; this env knob is a process-lifetime override.
When unset: falls through to persisted defaultModel.model, then to the hard-coded claude-sonnet-4-6.
Format: a model id string. For OpenRouter, use the prefixed name (anthropic/claude-sonnet-4.5, openai/gpt-5, google/gemini-2.5-pro, etc.). For Anthropic-native, use the bare id (claude-sonnet-4-6, claude-opus-4-7, claude-haiku-4-5-20251001). Resolution order (first non-empty wins): config.model (programmatic) > MINARA_DEFAULT_MODEL (this var) > persisted choice > hard-coded default.
Setting home: Not a user-facing setting

`AGENT_MAX_ITERATIONS`

max tool-calling loop iterations per turn.

What it controls: the ceiling on how many LLM→tool→LLM cycles the agent loop runs before throwing MaxIterationsError. Applies to the Phase 2 (data collection) part of the three-phase loop.
Consumed by: src/app.ts → AgentConfig.maxIterations.
When to set: you want tighter cost control (lower value) or need more iterations for complex multi-tool queries (higher value).
When unset: defaults to 30.
Format: positive integer.
Setting home: Not a user-facing setting

`AGENT_MAX_TOKENS`

pin the max_tokens ceiling for every LLM call inside the agent loop's tool-calling cycle. OPTIONAL OVERRIDE.

What it controls: when set, the value is forwarded verbatim as the max_tokens argument to every messages.create call. When unset, the agent derives the ceiling from the active model itself, in src/llm/model-output-limits.ts: the live provider listing first (Anthropic /v1/models max_tokens), then the published OpenRouter catalog ceiling, then a 32K fallback that logs a warning naming the model. The model-derived path is the default and the recommended posture: "no artificial cap" so long institution reports / deep-research tables / chat summaries finish without truncation. A turn that does hit the ceiling now fails loudly instead of returning a truncated answer as a success.
Consumed by: src/app.ts → AgentLoop.maxTokens.
When to set: only when you want a value DIFFERENT from the model's native ceiling — tight cost control on simple queries, or pinning to a smaller value for predictable per-turn billing.
When unset: agent uses the model's full output window (recommended).
Format: positive integer.
Setting home: Not a user-facing setting

`GATEWAY_HOST`

HTTP gateway bind interface.

What it controls: the network interface npm run serve (src/gateway/server.ts) binds. 127.0.0.1 / localhost = local only; 0.0.0.0 = every interface (reachable off this host).
Consumed by: src/gateway/serve-cli.ts (decideBind guard).
When to set: exposing the gateway beyond localhost (a LAN host, a Docker bridge). A non-loopback bind REQUIRES auth — either set GATEWAY_AUTH_TOKEN, or the gateway auto-generates one in non-interactive contexts and refuses to start interactively.
When unset: defaults to 127.0.0.1 (local only).
Format: an IP or hostname to bind.
Setting home: Not a user-facing setting

`GATEWAY_PORT`

HTTP gateway port.

What it controls: the port npm run serve (src/gateway/server.ts) binds for the REST/SSE API.
Consumed by: src/gateway/server.ts.
When to set: running the HTTP gateway in addition to — or instead of — the interactive REPL. Ignored by npm run dev.
When unset: defaults to 8080.
Format: integer 1-65535.
Setting home: Not a user-facing setting

`GATEWAY_AUTH_TOKEN`

HTTP gateway bearer-token.

What it controls: required Authorization: Bearer <token> on every inbound request to the HTTP gateway.
Consumed by: src/gateway/server.ts (via src/gateway/api.ts).
When to set: exposing the gateway on any network interface. The token is compared with constant-time equality.
When unset AND binding loopback (127.0.0.1): authentication is disabled and every request is accepted — safe only because nothing off this host can reach it. When unset AND binding a non-loopback interface, the gateway auto-generates a token in non-interactive contexts (Docker/CI, written to <dataDir>/gateway-token) or refuses to start interactively. Set MINARA_ALLOW_INSECURE_BIND=1 to force an unauthenticated public bind (not recommended).
Format: opaque high-entropy string. Generate with openssl rand -hex 32.
Setting home: Not a user-facing setting

`GATEWAY_CORS_ORIGINS`

browser cross-origin allowlist.

What it controls: which web origins a browser may read cross-origin (the Access-Control-Allow-Origin response header + the OPTIONS preflight). Non-browser callers (curl, the desktop shell, other servers) authenticate with the bearer token and are unaffected.
Consumed by: src/gateway/serve-cli.ts (resolveCorsOrigins) via src/gateway/api.ts.
When to set: serving the web UI from a DIFFERENT origin than the gateway on a non-loopback bind — e.g. the UI on https://app.example.com calling the gateway on https://api.example.com. List every browser origin.
When unset: a loopback bind allows all origins (*, unchanged local dev); a non-loopback bind denies all cross-origin browser reads by default — a same-origin UI (WEB_UI_DIST_DIR) and token-authenticated API clients still work.
Format: comma-separated origins (scheme://host[:port]), or * for any.
Setting home: Not a user-facing setting

`MINARA_ALLOW_INSECURE_BIND`

bypass the secure-bind guard.

What it controls: when set, the gateway serves on a non-loopback interface with NO authentication instead of refusing to start / auto-generating a token. Every request — including fund-moving endpoints — is accepted from anyone who can reach the port.
Consumed by: src/gateway/bind-security.ts (isInsecureBindAllowed).
When to set: last resort on a fully trusted, firewalled single-host network where you accept the risk. NEVER on a public-internet or shared network.
When unset: the secure-bind guard is active (the default, recommended).
Format: 1/true/yes/on to enable.
Setting home: Not a user-facing setting

`WEB_UI_DIST_DIR`

same-origin web-ui static root.

What it controls: when set to a built web-ui dist/ directory, the HTTP gateway serves that SPA at / (assets + client-side-navigation fallback to index.html) on the SAME origin as the API — so a desktop shell or single-origin deploy needs no separate static host and no CORS. The API (/v1/*) stays bearer-gated; only the static shell and /assets/* are public.
Consumed by: src/gateway/static-spa.ts (via src/gateway/api.ts).
When to set: packaging the desktop app, or serving UI + API on one port.
When unset: no static UI is served — the gateway behaves as a pure API server (the default for Docker / CLI).
Format: absolute path to an existing directory containing index.html.
Setting home: Not a user-facing setting

`WEBHOOK_PORT`

webhook gateway port.

What it controls: the port the optional webhook listener binds for inbound events (TradingView alerts, Minara push events, price-alert triggers that feed src/workflow/triggers.ts).
Consumed by: src/gateway/server.ts.
When to set: you're wiring external webhook sources into the workflow engine. Must differ from GATEWAY_PORT.
When unset: the webhook listener is not started — only scheduled cron triggers fire autonomous turns.
Format: integer 1-65535.
Setting home: Not a user-facing setting

`FILES_URL_BASE`

URL prefix for sandbox file downloads.

What it controls: the public prefix the agent rewrites local sandbox paths to when returning files to the client.
Consumed by: src/app.ts.
When to set: the HTTP gateway is served behind a reverse proxy and the caller needs an absolute URL (https://agent.example.com/v1/files).
When unset: defaults to the relative path /v1/files.
Format: absolute URL or relative path prefix, no trailing slash.
Setting home: Not a user-facing setting

`OFFLINE_MODE`

outbound HTTP kill-switch.

What it controls: every outbound fetch through src/tools/_shared/fetch-timeout.ts short-circuits with a blocked error. All tool network calls refuse.
Consumed by: src/tools/_shared/fetch-timeout.ts.
When to set: running deterministic tests or air-gapped demos where any outbound call would be a bug.
When unset: network calls behave normally.
Format: 1 / true / yes / on to enable. Anything else = off.
Setting home: Settings → Preferences (schema key)

`HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY` / `NO_PROXY`

outbound proxy.

What it controls: the forward proxy used by Minara-owned transports: model calls, market-data and provider fetches, MCP servers, and the headless browser. Python / node / shell children also receive proxy environment variables while Settings > Preferences > Safety > Pass proxy settings to local commands is enabled. Checked in the order HTTPS_PROXY, HTTP_PROXY, ALL_PROXY; the first one set wins, upper- and lower-case names both read.
Consumed by: src/config/egress/resolve.ts, which parses the boot environment once and hands the result to one adapter per transport. Desktop can replace only its managed OS-proxy route at runtime. Nothing else reads these variables.
When to set: the machine reaches the internet only through a proxy. On Minara Desktop the OS proxy is detected and injected automatically; OS HTTP proxy and PAC changes apply to new requests, reconnects, browser launches, and child processes without restarting Minara. Setting these variables by hand is for the CLI, gateway, and Docker, and remains a boot-time setting that requires a restart to change.
When unset: Minara-owned connections go out direct. Child processes receive no proxy variables from Minara, but system-wide routing such as TUN mode may still carry their traffic.
Format: an http:// or https:// URL, optionally with credentials (http://user:pass@proxy:3128). A SOCKS URL is logged and ignored — the proxy has to speak HTTP CONNECT. NO_PROXY is a comma-separated list of hosts (CIDR ranges are honoured by the children and the browser, not by the agent process itself); loopback and the private ranges are always bypassed whether listed or not.
Note: while child-process proxy inheritance is enabled, a URL carrying credentials is visible to model-authored local code. Minara warns once per process when this occurs. Turn off the Safety preference above to stop the environment handoff; this does not isolate the child from direct or TUN-routed networking.
Setting home: Not a user-facing setting

`CLOUD_SYNC_AUTO`

sync with your Minara account in the background.

What it controls: whether this device mirrors itself against your Minara account unattended, roughly every five minutes. Syncing on demand is always available and does not depend on this; the switch only governs the passes the user did not ask for.
Consumed by: cloudSync.auto in the runtime Preferences schema and src/app/sync.ts. Which kinds of data participate is chosen separately (see CLOUD_SYNC_CHAT and CLOUD_SYNC_PERSONALIZATION).
When to set: you use Minara on more than one device and want them to keep up with each other without being asked.
When unset: nothing is uploaded until someone syncs on demand. Conversations hold local paths and private context, so unattended passes are off by default.
Format: 1 / true / yes / on to enable. Anything else = off.
Setting home: Settings → Preferences (schema key)

`CLOUD_SYNC_CHAT`

include conversations in the sync.

What it controls: whether conversations are part of what gets mirrored. Only what you and the agent said is sent — tool calls, tool results and reasoning stay on this device.
Consumed by: cloudSync.chat in the runtime Preferences schema.
When to set: set it to false to keep syncing on for other data while leaving conversation text on this machine.
When unset: conversations are included, but only once this device syncs.
Format: 0 / false / no / off to exclude. Anything else = included.
Setting home: Settings → Preferences (schema key)

`CLOUD_SYNC_PERSONALIZATION`

include what Minara remembers about you.

What it controls: whether the short factual notes Minara keeps about you are part of what gets mirrored. These are single sentences, not whole conversations.
Consumed by: cloudSync.personalization in the runtime Preferences schema.
When to set: set it to false to sync conversations without sharing the derived notes.
When unset: the notes are included, but only once this device syncs.
Format: 0 / false / no / off to exclude. Anything else = included.
Setting home: Settings → Preferences (schema key)

`CLOUD_SYNC_USER_TAGS`

include the answers that describe how you invest.

What it controls: whether the dimensions you answered about yourself (risk, horizon, markets, and the rest) are part of what gets mirrored.
Consumed by: cloudSync.user-tags in the runtime Preferences schema.
When to set: set it to false to keep those answers on this device while still syncing everything else.
When unset: they are included, but only once this device syncs.
Format: 0 / false / no / off to exclude. Anything else = included.
Setting home: Settings → Preferences (schema key)

`CLOUD_SYNC_PROFILE`

include your own instructions and watchlist.

What it controls: whether the settings you chose yourself travel — your custom instructions, what Minara is allowed to bring into an answer, the wallets you watch, and your watchlist. The summaries Minara derives from your trading stay on the device that built them.
Consumed by: cloudSync.profile in the runtime Preferences schema.
When to set: set it to false to keep those settings per-device.
When unset: they are included, but only once this device syncs.
Format: 0 / false / no / off to exclude. Anything else = included.
Setting home: Settings → Preferences (schema key)

`CLOUD_SYNC_WORKFLOW`

include automations and cloud workflows.

What it controls: whether automations and cloud workflows are part of what gets mirrored. The first pass can take a while. Some may not run on this device because the two sides are built differently — those stay on the account and are reported as items this device could not open, not as a failed sync.
Consumed by: cloudSync.workflow in the runtime Preferences schema.
When to set: set it to true when you want automations to travel with conversations and memories.
When unset: automations are left out until turned on in Sync settings. Rebuilding a cloud workflow on this device is opt-in.
Format: 1 / true / yes / on to enable. Anything else = off.
Setting home: Settings → Preferences (schema key)

`LOG_LEVEL`

logger verbosity.

What it controls: minimum level emitted by src/core/logger.ts. Messages below this are dropped.
Consumed by: src/core/logger.ts.
When to set: debug while developing a new tool / skill, warn or error for quiet production deploys.
When unset: defaults to warn.
Format: one of debug | info | warn | error.
Setting home: Not a user-facing setting

On this page