Environment Variables

This page covers the convention for how minara-agent-v2 loads env vars and the required steps for introducing new ones. For the per-variable reference with defaults, formats, consumer files, and "what breaks if unset" for every variable the agent reads, see Reference → Environment Variables.

The canonical template lives at .env.example at the project root. Keep that file in sync with both pages.

MINARA_ is reserved for Minara-platform-specific variables (MINARA_API_KEY, MINARA_BASE_URL, MINARA_SKIP_FUND_CONFIRM, MINARA_DATA_DIR, MINARA_OPENAI_BASE_URL, MINARA_OPENAI_CHAT_PATH). Agent-loop infrastructure variables (gateway, log, model, scenario, memory knobs) drop the prefix.

TL;DR Convention

Any new skill or tool that needs an API key, secret, token, or overridable URL MUST:

1. Read it via process.env.<NAME> at factory/initializer time. Never hard-code secrets. Never accept them as CLI args you echo.

2. Append a documented entry to .env.example in the same commit. The entry must spell out: what it controls, which skill/tool consumes it, when an operator would set it, the default behavior when unset, and the accepted value format. One-line stubs (# FOO_KEY=) are rejected — the template is the first thing a new operator reads. Update this page in the same commit so the published docs stay in sync.

3. For domain skills (apps/agent/src/skills/builtin/*.ts or apps/agent/src/skills/external/<id>/), declare the var in requires_env so the SkillRegistry hides the skill entirely when the var is missing:

   export const myNewSkill: DomainSkill = {
     id: "research.my_provider",
     // ...
     requires_env: ["MY_PROVIDER_API_KEY"],
   };

4. For tools (apps/agent/src/tools/*.ts), the factory should return an empty ToolEntry[] when the env var is missing. The tool registry silently excludes unregistered names, so downstream skill tool_names references will gracefully degrade:

   export function createMyProviderTools(): ToolEntry[] {
     const apiKey = process.env.MY_PROVIDER_API_KEY;
     if (!apiKey) return [];
     // ...
   }

5. Never commit a real secret. .env is git-ignored; .env.example is the committed template with blank values.

How .env loading works

Loading is handled by apps/agent/src/config/load-env.ts — a side-effect module that calls Node 22's built-in process.loadEnvFile(".env"). It's imported as the very first line of every entrypoint:

• apps/agent/src/gateway/cli.ts — REPL mode
• apps/agent/src/gateway/server.ts — HTTP mode

ESM evaluation order guarantees the loader runs before any downstream module that reads process.env.<NAME> at import time.

Precedence: variables already exported by your shell / CI / systemd win over values in .env. The loader does not overwrite existing keys. This matches Node's default behavior and is the safest rule (no surprise masking of CI-injected secrets).

No dotenv dependency. We rely purely on process.loadEnvFile, stable since Node 22.5. Missing .env is a no-op (not an error).

Inventory

For detailed per-variable documentation (defaults, formats, consumer files, "what breaks if unset"), see Reference → Environment Variables. The tables below are a quick-reference summary.

LLM providers

At least one must resolve (directly or via a saved OAuth profile from minara login) or the agent refuses to start.

Extended thinking

Claude 3.7+ / Sonnet 4.x / Opus 4.x / Haiku 4.5+ support the thinking API parameter. The model decides per-turn how much (if any) of the budget to actually spend reasoning — simple queries spend ~0 thinking tokens; complex synthesis can use the full budget. Other providers (OpenAI o1/o3) reason automatically; the param is accept-and-ignore for them.

The web-ui's existing ReasoningBlock (collapsed by default with a streaming preview) renders the trace for both regular chat and the institution-mode persona cards. For models WITHOUT native extended thinking, the chat input toolbar shows a manual Thinking toggle that prepends a "think step by step" instruction to the user message.

web_search provider chain

web_search walks a provider chain (first non-empty wins). Native LLM-provider search runs first when configured, then external HTTP providers, then the always-available DuckDuckGo Lite fallback.

Each provider is "transient-failure transparent": exceptions or 0-result responses fall through to the next chain entry. The web_search tool also accepts an explicit engine parameter (auto / exa / firecrawl / anthropic_native / tavily / google / brave / duckduckgo) for ops debugging.

Minara core

HTTP gateway

Safety and fund-moving

Hybrid memory retrieval

When EMBEDDING_PROVIDER=disabled (default) the hybrid search code path is inert: every memory row stays at embedding_state='pending' with a NULL embedding column and searchMemoriesHybrid falls through to the existing FTS5 BM25 path with byte-identical results. Operators only enable this when they want the cross-vocabulary recall lift (e.g. a Chinese query 山寨币最近怎么样 retrieving an English altcoin drawdown lesson). The write path stays sync — embeddings happen in a queueMicrotask after the row is committed, so user-facing latency is unchanged.

When the provider is enabled but transient API failures happen, rows land at embedding_state='failed'. minara doctor (Phase E1) exposes the per-state counts so operators can spot heaps; minara doctor --fix --apply (Phase E2) backfills via MemoryStore.backfillEmbeddings(). Both failed and pending are eligible for backfill — the same row may cycle until a successful embed lands it at embedded. Rows shorter than 10 chars or that trip the methodology injection scanner land at skipped and never embed.

Backtesting feedback loop (Sprint 6 — online outcome filler)

Periodic job that closes the learning loop for trades executed in-session. Computes a post-trade outcome ("+5.20% in 24h"), feeds it to EvaluationLoop.evaluatePacked, and (when LEARNING_RECORD_USAGE=true) calls MethodologyStore.recordUsage(id, was_correct) for every methodology consulted during the originating turn.

Does not replay historical trades. Only evaluates rows already in trade_history. Entirely dark by default (BACKTEST_ENABLED=false).

Rollout protocol (plan dapper-coalescing-shell §Sprint 6):

1. Set BACKTEST_ENABLED=true + BACKTEST_DRY_RUN=true for one cron cycle. Inspect shadow_runs WHERE facet='backtest_outcome' — check that outcome strings match ±N.NN% in Xh and skip reasons are sensible.
2. Flip BACKTEST_DRY_RUN=false. The runner now writes back trade_history.outcome + state, and new methodologies may be created by evaluatePacked. recordUsage is still a no-op.
3. Flip LEARNING_RECORD_USAGE=true. The Wilson counters begin to update on every evaluation. Monitor methodologies.times_used + times_correct delta per day.

Personalization rebuild (M3.2 event-driven thresholds)

Minara learns your trading preferences from every conversation via the PersonalizationRebuilder. Pre-M3.2 the rebuilder ran every 10 minutes on a cooldown. M3.2 makes it event-driven + threshold-gated: data writes (trades, memories, chat turns) emit events that wake the rebuilder, and each rebuild must clear two independent gates — a minimum new-input count and a minimum elapsed time since the last rebuild. Neither gate alone triggers a rebuild; both must be true.

The 60-minute safety-net scheduler is still there to cover lost events (e.g. process restarts between a write and its subscriber), but on a quiet system it produces zero LLM calls and zero info logs.

Trading summary thresholds

Raise the thresholds if your trading frequency causes the summary to churn too often; lower them if you want the summary to converge as fast as possible during backtests or onboarding.

Memory extraction thresholds

rebuildMemories scans chat_turns rows written since the cursor last_indexed_chat_id and extracts discrete facts. By default it uses an ADD-only prompt (no UPDATE/DELETE), so contradictions are appended alongside prior facts and resolved at retrieve time. When MEMORY_CONSOLIDATION_ENABLED is on, a follow-up resolver pass instead decides ADD / UPDATE / SUPERSEDE per fact, so stale and contradictory rows are tidied at write time (see Minara Memory). Each extracted fact is written as a row in the shared memories table with fact_type, attributed_to, entities_json, and linked_memory_ids metadata.

Shared knobs

Operational tip: on a brand-new deployment, set FIN_PROFILE_TRADING_SUMMARY_MIN_NEW_TRADES=1 and FIN_PROFILE_MEMORIES_MIN_NEW_TURNS=2 for the first day so the rebuilder warms up quickly. Restore defaults after the profile stabilizes.

Off-agent history mirror

The personalization rebuilder now consumes three sources: local trade_history (agent in-session), perps_fills (cross-sub mirror of Minara's /v1/perp-wallets/fills), and external_spot_activities (Minara's /v1/tx/cross-chain/activities). The knobs below shape how MinaraHistorySync keeps itself up to date and how much of the mirror the LLM rebuild reads.

Sync trigger model. Three paths cause MinaraHistorySync.scheduleSync() to fire: (1) any trade:recorded event (the agent just executed a trade — the user likely also did something on web/mobile), (2) the PersonalizationRefreshTask's hourly safety-net tick (catch missed events), and (3) the explicit /refresh-personalization --force / POST /v1/profile/refresh path. The 5-minute throttle dedupes these calls so the API is never hit more than once per window.

Watermark granularity. minara_history_sync_state is keyed by (source, sub_account_id). A single sub-account's transient failure neither pollutes its peers' watermarks nor the global spot cursor.

Hyperliquid perps

MINARA_HL_DEX_DISCOVERY controls how widely Minara discovers Hyperliquid named perp DEXes when building perps snapshots and syncing trade history.

Strategy Studio (BETA)

Two operator knobs control the local strategy-codegen subagent and the default authoring path picked by the minara.strategy-studio skill plus the /strategy-new REPL command. Both default to sensible values, so leaving them unset is fine.

Institution Mode (multi-agent firm simulation)

The minara_institution_analyze tool convenes a 6-phase pipeline (4 analysts in parallel → bull/bear research debate → research manager → trader → 3-way risk debate → portfolio manager) for high-stakes single-asset analysis. Modeled after TradingAgents; default values for round counts are anchored verbatim to that project's default_config.py, while timeouts / token caps follow Minara's deep_research and agent-loop conventions.

All variables below are agent-loop infrastructure — no MINARA_ prefix per the project convention. Leaving them all unset gives the TA-anchored defaults.

Single-model policy. Every role in the pipeline (analysts, debate participants, Research Manager, Trader, risk personas, Portfolio Manager, Allocator) runs on the operator's selected agent model — same provider/model the rest of the agent uses. There is no per-role override. To run synthesis on a stronger model, switch the agent's default model for the whole session.

Cost note: a single institution run is roughly 25 LLM calls × 4 K output tokens ≈ 10⁵ output tokens — about $1–3 on Sonnet-class models at default settings. Document this prominently if exposing the tool to end users.

Hardcoded constants (NOT operator-tunable env vars in v1):

• Phase-1 analyst concurrency = 4 (the analyst count; Promise.all over the four slots, no semaphore library).
• Subagent inner-loop turn cap = 5 turns. Matches Minara's strategy-code-subagent discipline; analysts only need 1–3 tool calls before producing their report.
• Per-LLM-call timeout = wallClock / 10, with a 5-second floor.
• Output language = inherits from existing user-message language detection (the same pattern deep_research uses); internal debate turns stay in English regardless, only the final report localizes.

If real operations need to tune any of the hardcoded constants, lift them to env vars in a follow-up PR.

Self-learning + Phase B reflection (v2 PR 1 / PR 2)

The v2 self-learning track persists every institution run into three SQLite tables (institution_runs, institution_role_outputs, institution_reflections), runs a multi-window Phase B reflection ladder (1d/7d/30d/90d/180d/365d) on still-open positions, and writes a "lazy" reflection on stale prior runs before each new institution call (Phase 0 retrospective refresh). All variables below are agent-loop infrastructure; no MINARA_ prefix per project convention.

Analyst recovery + canonical-asset preflight

Each Phase-1 analyst slot runs the model in a free tool-calling loop, then runs a single synthesis turn that asks for a structured prose summary in HEADLINE / KEY FINDINGS / CONFIDENCE format. The orchestrator parses the prose directly into an AnalystReport — no forced-submit toolChoice step, no retry harness. When the synthesis is empty or unparseable, the orchestrator falls back to buildSubagentSummaryReport, which always emits a usable report (either citing the captured tool data when tools succeeded, or falling back to the analyst's role-domain default reasoning when they didn't). Downstream phases always receive a usable summary; the legacy data_gap flag has been retired, and there are no operator-tunable retry budgets — the contract is "always produce something usable" and there is no budget to tune.

Before Phase 1 dispatches, an unknown ticker triggers a server-side canonical-identity preflight: parallel CoinGecko / CMC / DexScreener lookups normalised to a chain+contract (or chain+native) identity, persisted in a SQLite cache with per-outcome TTL.

Direction-aware scoring. Phase B records raw_return flipped for short positions and zeroed for flat decisions (a profitable short on a falling underlying records a positive return, not a negative one). Long / unspecified directions pass through unchanged. See reflect.ts applyDirection().

Retryable data outages. A standard window evaluation that fails to fetch prices writes a data_unavailable placeholder; on the next cron pass the placeholder is UPSERT'd to ok once prices return. nextDueStandardWindow filters by status='ok' so the window is re-evaluated until it succeeds.

Offline learning-config tuning (Phase B gate)

The LEARNING_CONFIG hyperparameters in apps/agent/src/learning/methodology-store.ts are currently hand-picked. A future Bayesian-optimization harness will tune them against Sprint 6's accumulated P&L attribution data; the code lives in apps/agent/src/learning/replay/ and tools/tuning/ once built.

The harness is offline-only — it runs via CLI / Python subprocess, never as part of the request path. Until data accumulates to the readiness gate (≥100 evaluated trades, ≥20 unique methodology hits — see minara learning stats), the whole path stays disabled.

Full roadmap + objective-function design in apps/agent/docs-src/bo-learning-config-tuning.md.

Methodology self-optimization loop (Phases 1-7)

End-to-end pipeline for capturing investment-advice decisions, backtesting them at multiple horizons, and learning per-asset-class methodology thresholds via Bayesian optimization. All sub-systems are dark-landed — every env var defaults OFF and activating any one is a deliberate operator action.

Phase 1 — Decision capture

Turn-end hook runs an independent Haiku-class summarizer that extracts {asset, decision, confidence, quoted_price} from advice-flavored turns and persists to decision_history. Fire-and-forget by default; zero user-visible latency change.

Phase 2 — Multi-horizon backtest + hallucination check

Cron runner fills decision_outcomes with 1d/3d/1w/1m returns. Before filling outcomes, it compares agent_quoted_price against the real historical price; if the deviation exceeds HALLUCINATION_MAX_PRICE_DELTA_PCT the decision is flagged and excluded from downstream learning.

Phase 3 — Reward

Reward function collapses the 4-horizon return vector into a single scalar per decision. BUY rewards upward moves, SELL rewards downward moves, HOLD rewards neutrality (|return| ≤ threshold).

Phase 4 / 7 — Methodology instance dispatch

Per-(template, asset_class) threshold overrides. Phase 4 ships the scaffolding; Phase 7 flips the prompt-builder to prefer instance overrides. off keeps pre-Phase-4 behavior exactly.

Instance dispatch is default-on: the prompt-builder merges BO-tuned instance overrides onto template defaults when available. Revert to template-only resolution via the DISABLE_METHODOLOGY_INSTANCE_DISPATCH=1 off switch (documented in the agent-loop section above).

Phase 6 — BO tuning cycle

Python harness (in tools/tuning/) runs bayesian-optimization per eligible bucket, driven by a TS cycle orchestrator that evaluates 6 eligibility gates + asset-class profiles.

Rollout order:

1. DECISION_CAPTURE_ENABLED=true — start recording advice turns.
2. Wait ~30 days for data.
3. DECISION_BACKTEST_ENABLED=true + DECISION_BACKTEST_DRY_RUN=true — shadow mode 1 week.
4. DECISION_BACKTEST_DRY_RUN=false — live backtest writes.
5. Check minara learning stats reports READY_FOR_BO=true.
6. METHODOLOGY_INSTANCE_TUNING_ENABLED=true — activate BO cycle.
7. Instance dispatch is on by default; keep DISABLE_METHODOLOGY_INSTANCE_DISPATCH unset.

Builtin tools

Every row is optional. Missing var disables the feature silently.

Messaging platforms (extended set)

Eleven additional IM and consumer-social platforms ship on top of the original seven (telegram, discord, slack, email, whatsapp, signal, home_assistant). Each platform has its own env-var block; missing values disable both outbound and inbound for that provider silently (the route 404s and the gateway drops out of the live map).

Detailed setup steps, inbound webhook URLs, and signature recipes live in the Messaging per-platform pages. The fastest path to wiring credentials is minara gateway add (interactive picker, lists all 18 platforms with their current configured / not-configured status).

Lark / Feishu

WeCom (企业微信)

DingTalk (钉钉)

WeChat OA (公众号)

QQ Bot

LINE

Mattermost

Microsoft Teams

Google Chat

BlueBubbles (iMessage)

Matrix

Client-outbound inbound daemons

Telegram, Discord, Slack, Mattermost, QQ, DingTalk, and Lark each support a client-outbound inbound daemon: the agent connects out and holds a long connection (long-poll or WebSocket) instead of running a public webhook server. This is what makes two-way chat work on a personal machine with no public IP, no tunnel, and no third party. Each daemon auto-starts when the platform's outbound credentials are configured and no public webhook is wired for it; the switches below are an explicit tri-state override (unset = auto, 1 = force on, 0 = force off).

MCP integrations

Native provider keys (PR-A → PR-G migration)

The provider-routing rollout retired the vendored coinglass / coinank / query-token-audit / meme-rush / polymarket / okx-dex-token / okx-wallet-portfolio / okx-security / okx-dex-trenches SKILL.md packages. Their capabilities now live in the native priority chains under apps/agent/src/tools/_shared/ + the analysis.derivatives / market.flows / security.token / discovery.dex / prediction.markets skills. Env vars listed below gate the native providers, not legacy SKILL.md packages.

The native prediction.markets skill is read-only (Polymarket's public Gamma + CLOB read endpoints) and needs no env. The retired external.polymarket SKILL.md used PRIVATE_KEY / RPC_URL / POLY_BUILDER_* for authenticated order placement; that write path is not yet ported and those env vars no longer have a consumer in the agent.

Surviving vendored external skills

The PR-G deletion left these vendored SKILL.md packages in place (they cover capabilities the native priority chain doesn't yet absorb):

Methodology learning loop — case attribution + synthesis (Phase 1-4)

Tuning knobs for the methodology learning loop introduced in the Phase 1-4 series (case-recorder, attribution cron, synthesis). All are optional — defaults are tuned for production. Most operators only ever touch the off switches and the synthesis thresholds.

Off switches (incident response)

Set to 1 / true / yes / on to enable. Unset / any other value leaves the path active. Hot-reads — flip without restart.

Synthesis tuning (Phase 4 D)

Price quality (Phase 3 F4.3)

Per-asset-class daily absolute return caps. A 7d window scales by sqrt(7). Rejects single-day FX prints, split-adjusted spikes, delisted-ticker zeros from polluting Wilson.

Case-recorder housekeeping (Phase 2)

Operating the learning cron

The agent does NOT auto-schedule the learning cron. Wire one of the minara learning subcommands to a system cron / launchctl / systemd timer. Recommended daily cadence:

# Daily at 03:00 — sweep, attribute, synthesize. Idempotent so any
# missed run is replayed on the next tick.
0 3 * * *  /usr/local/bin/minara learning cron --json >> /var/log/minara-learning.log

CLI surface (Phase 4 E):

minara learning methodology explain <id>          # current state + audit
minara learning methodology lifecycle [--kind k]  # tail audit log
minara learning methodology cases [--asset c]     # tail case table
minara learning attribute                         # one 7d attribution pass
minara learning synthesize [--asset c]            # one synthesis pass
minara learning sweep-orphans                     # one orphan sweep
minara learning cron                              # all of the above

Methodology audit subsystem (passive observer)

A read-only audit subsystem layers over the learning loop and emits a composite health score. Six dimensions feed the composite: synthesis decision stability, graduation false-positive rate, attribution integrity, asset-class coverage, quarantine churn, and cron health. The subsystem never mutates learning state — its only write is one row per pass to methodology_audit_reports. An end-to-end test hashes the four learning tables before and after every audit pass to catch any regression that introduces a write.

The cron is cooperative with the agent loop. Every tick checks the shared BusyTracker. If a user turn is in flight, or the agent has been idle less than the configured threshold, the tick is deferred. A starvation guard runs the pass after N consecutive deferred ticks so a permanently busy installation doesn't lose audit coverage. Mid-pass, the orchestrator yields to the event loop between each SQL stage and pauses on the busy tracker if a turn arrives.

Default cadence is once per day. cron_health reads the methodology_cron_runs heartbeat table that src/learning/methodology-cron.ts writes at the tail of every learning tick, so a quiet attribution lane (no eligible cases) is not misread as a dead loop.

CLI surface:

minara learning audit run [--window-days N]  # inline single pass
minara learning audit show [--latest|--pass <id>]
minara learning audit trend [--days N]       # composite history + sparkline
minara learning audit findings [--severity high|medium|low]

Fund-confirm bypass (advanced — production caveat)

MINARA_SKIP_FUND_CONFIRM is documented in CLAUDE.md §3b. When set, fund-moving handlers skip the confirm: true requirement and execute on the first call. The case recorder mirrors this — turns executed under the bypass count as fund_moving_executed for Wilson attribution. Do NOT set in interactive or prod.

Proactive Wealth Agent

The background supervisor loop that runs each activated mandate (marks positions to market, take-profit / cut-loss / rebalance, snapshots PnL, and writes the work log), plus the slower re-discovery that hunts for fresh opportunities. All three are also editable live at Settings → Proactive (and inside the Proactive module's own settings tab); the env vars below are the boot fallback. Multi-worker deployments only run the loop on the worker with IS_PRIMARY_WORKER=1.

x402 paywall pre-authorization (PR-X)

These variables bound the "pay-once-then-auto-pay" feature for HTTP 402 / x402 paywalls. The grant call itself ALWAYS goes through the §3b two-step confirm gate; subsequent payments matching an active session's scope skip the per-call user prompt and execute directly via transfer_token. Every auto-spend writes audit metadata (session id + remaining budget) to the response so the user can trace each charge.

Wired into:

• apps/agent/src/minara/x402-preauth-store.ts — SQLite store + cap math
• apps/agent/src/minara/x402-preauth-config.ts — env loader + cap helpers
• apps/agent/src/tools/_shared/confirm.ts — shouldAutoExecuteX402 helper
• apps/agent/src/tools/trade.ts — transfer_token consults auto-execute first
• apps/agent/src/tools/x402-preauth.ts — x402_preauth_grant / _list / _revoke
• apps/agent/src/skills/builtin/x402-payment.ts — 4-option preview prose
• apps/agent/src/gateway/repl-commands.ts — /x402 preauth CLI surface

scope=any + ttl=forever is the most permissive grant possible. The REPL /x402 preauth grant handler requires double-explicit confirmation for that combination; the LLM tool x402_preauth_grant never proposes it automatically (the x402-payment skill prompt spells this out explicitly).

OpenClaw workspace integration

The agent reads + writes a workspace dir (default ~/.minara/workspace/, override via MINARA_WORKSPACE_DIR or the --workspace flag) containing markdown files modeled on OpenClaw's AGENTS.default.md schema: SOUL.md (identity), AGENTS.md (rules), IDENTITY.md, USER.md, MEMORY.md (curated long-term), HEARTBEAT.md (between-session memo), BOOTSTRAP.md (first-run only), TOOLS.md (env-specific tool notes), and memory/YYYY-MM-DD-*.md (daily logs).

Templates ship under apps/agent/src/workspace/templates/. The boot path calls seedWorkspaceIfMissing() automatically inside createApp() so a fresh install gets the full file set without forcing the operator to run minara setup. The seed is idempotent — files the user has edited are never overwritten. HEARTBEAT.md is intentionally NOT seeded (the agent writes a real one at the end of its first turn; seeding stale state would lie).

The Web UI's Settings → Workspace panel edits the runtime files at ~/.minara/workspace/ through the gateway's /v1/workspace/files endpoints with sha256 optimistic concurrency.

Wired into:

• apps/agent/src/workspace/seed.ts — seedWorkspaceIfMissing + atomicWriteFile
• apps/agent/src/workspace/heartbeat-writer.ts — per-turn ## State writer
• apps/agent/src/workspace/daily-log-writer.ts — per-session daily journal
• apps/agent/src/workspace/dreaming-task.ts — periodic MEMORY.md consolidation
• apps/agent/src/workspace/bootstrap-handler.ts — archive on BOOTSTRAP_DONE
• apps/agent/src/workspace/soul-change-detector.ts — disclose SOUL.md edits

MINARA_WORKSPACE_DIR and the --workspace CLI flag override the default ~/.minara/workspace/ path for both reads and writes, including the auto-seed and the gateway editor. Useful when pointing Minara at an existing OpenClaw workspace (--workspace ~/.openclaw/workspace).

Deep Research report rendering

Shortcut questions (Chat landing page)

The /v1/shortcut-questions endpoint feeds the Chat landing page's chip-row + paginated question list. Each category has a hand-authored fixed list (always returned) and an LLM-generated dynamic list that refreshes on a cadence.

Spot deposit watcher (Portfolio Deposit modal)

The /v1/wallet/deposits/watch SSE endpoint detects inbound stable transfers in real time so the Deposit modal can flip from "Waiting for your deposit…" to a green "credited" pill without the user having to refresh. Each chain has its own JSON-RPC transport (Arbitrum + 6 other EVM chains via eth_getLogs, Solana via getSignaturesForAddress on the user's USDC token accounts). The agent ships with foundation-grade public RPC fallbacks per chain; operators can swap each one for a paid endpoint via the variables below.

System resource metrics (Dashboard System status row)

The /v1/system-metrics endpoint feeds the Dashboard's System status panel with CPU, memory, disk-free + sandbox-folder size, gateway network throughput, and recency-weighted LLM token throughput. CPU / memory / disk sample every 5s; network is counted per request; tokens are recorded per turn from agent-loop.

Checklist for adding a new env var

Before merging:

• Var is read via process.env.<NAME> with a sensible fallback (or explicit feature-gate if absent)
• Entry added to .env.example in the correct section, with a detailed comment covering purpose, consumer, when to set, default-when-unset, and value format (no one-line stubs)
• Entry added to the inventory above, matching the .env.example prose
• For domain skills: requires_env: ["<NAME>"] is set so the skill self-hides when the var is missing
• For tools: factory returns [] when the var is missing (never throws at boot)
• Var name follows the convention <PROVIDER>_API_KEY / <PROVIDER>_TOKEN / <PROVIDER>_<FIELD> — UPPER_SNAKE, provider prefix first
• No real secret value is committed anywhere