Environment variables

Tier-0 (core) vars the runtime always requires, plus per-plugin vars contributed by each bundled plugin’s configSchema.

How env validation works

The runtime composes one big Zod schema at boot: the Tier-0 base schema (always required) plus every loaded plugin’s configSchema. process.env is validated against the merged schema. Missing required vars fail boot with [boot-error] Plugin '<name>' env validation failed for '<field>'.

Disabling a plugin (via features or autoDetect) removes its env requirements automatically.

Tier-0 (core)

Always required by the runtime. Source: packages/oracle-runtime/src/config/base-env-schema.ts.

Runtime

Variable	Type	Default	Notes
NODE_ENV	'development' | 'production' | 'test'	'development'
PORT	number (coerced)	3000	Override at app.listen(port) if needed.
ORACLE_NAME	string	—	Required.
CORS_ORIGIN	string	'*'	Wildcard disables credentials.
NETWORK	'mainnet' | 'testnet' | 'devnet'	—	Required.

Matrix

Variable	Type	Default	Notes
MATRIX_BASE_URL	string	—	Required.
MATRIX_RECOVERY_PHRASE	string	—	Required.
MATRIX_STORE_PATH	string	'./matrix-storage'	Must persist across restarts.
MATRIX_ORACLE_ADMIN_USER_ID	string	—	Required.
MATRIX_ORACLE_ADMIN_PASSWORD	string	—	Required.
MATRIX_ORACLE_ADMIN_ACCESS_TOKEN	string	—	Required.
MATRIX_ACCOUNT_ROOM_ID	string	—	Required.
MATRIX_VALUE_PIN	string	—	Required.

Storage

Variable	Type	Default	Notes
SQLITE_DATABASE_PATH	string	—	Required. Must persist across restarts.

Blocksync / chain

Variable	Type	Default	Notes
BLOCKSYNC_GRAPHQL_URL	string	—	Required.
ORACLE_DID	string	—	Required. The oracle’s own DID (did:ixo:ixo1...) — the signer identity used by the UCAN service and the auth middleware.
ORACLE_ENTITY_DID	string	—	Required. The oracle’s on-chain entity record DID. Distinct from ORACLE_DID — do not conflate them.
SECP_MNEMONIC	string	—	Required.
RPC_URL	string	—	Required.

Auth / UCAN

Always present. Both are z.coerce.number() — set them as plain integer strings in .env.

Variable	Type	Default	Notes
UCAN_AUTH_MAX_TTL_SECONDS	number (coerced)	900	Max lifetime (seconds) the oracle accepts for a user auth invocation. Bounds the server-side replay window regardless of the TTL the client declares. Default 15 minutes.
UCAN_REAUTH_PROMPT_THROTTLE_SECONDS	number (coerced)	21600	Throttle window (seconds) between “please re-authorize” prompts posted into a user’s Matrix room when their stored delegation is missing or expired. Default 6 hours.

LLM

Variable	Type	Default	Notes
LLM_PROVIDER	'openrouter' | 'nebius'	'openrouter'
OPENAI_API_KEY	string	—	Optional.
OPEN_ROUTER_API_KEY	string	—	Required if LLM_PROVIDER=openrouter.
NEBIUS_API_KEY	string	—	Required if LLM_PROVIDER=nebius.

Cross-field check (validateLlmProviderKey): the API key for the selected LLM_PROVIDER must be present — OPEN_ROUTER_API_KEY when LLM_PROVIDER=openrouter (the default), NEBIUS_API_KEY when LLM_PROVIDER=nebius. A missing key fails boot with a named-field error (e.g. OPEN_ROUTER_API_KEY / NEBIUS_API_KEY) rather than a generic upstream 401 at request time. The per-role model ids are hardcoded per provider — there is no env var to swap the main model id (use the resolveModel hook for that).

Latency tuning

Variable	Type	Default	Notes
MAIN_REASONING_EFFORT	'low' | 'medium' | 'high'	'medium'	Extended-thinking effort for the main agent role only. Sub-agent reasoning is unchanged. Lower values reduce time-to-first-token at some cost to hard multi-step reasoning; higher values do the reverse. 'medium' preserves current behaviour, so leaving this unset is safe.

Two related latency wins ship always-on — there is no env var to disable them:

• Request-path caches. Three wins ship together. The per-user SqliteSaver is reused across the two build-time hook calls per turn instead of being rebuilt on each call. The agent builder reads prior build-time checkpoints via a light path that skips the message-history join (O(1) instead of O(history)). The Memory Engine userContext cache is keyed by roomId instead of sessionId, so a fresh session for the same room reuses the cached context.
• Memory-context compaction. The ## What you know about the user prompt block is deduped across all six memory buckets (entities collapsed by name, keeping the richest summary; facts / episodes / communities collapsed by normalized text — lowercase, punctuation stripped, whitespace collapsed) and bounded by fixed internal caps (per-entity summary and whole-block budget). When either cap trims content, the block ends with a _(More remembered — ask me to recall.)_ footer so trimmed detail stays reachable via the memory tool. No unique fact is dropped; paraphrases survive.

Misc

Variable	Type	Default	Notes
ORACLE_SECRETS	string	''	Comma-separated KEY=value pairs surfaced as x-os-* headers to capabilities.
LIVE_AGENT_AUTH_API_KEY	string	''	Optional.

LangSmith tracing (optional)

Variable	Type	Default	Notes
LANGSMITH_TRACING	string	—	Set to 'true' to enable.
LANGSMITH_API_KEY	string	—
LANGSMITH_PROJECT	string	—
LANGSMITH_ENDPOINT	string	—	Optional override of the LangSmith API URL.

Declared in the base schema so they show up in qiforge-cli env output. LangChain auto-wires when these are present in process.env; the runtime never reads them directly.

Per-plugin

Only required when the named plugin is loaded.

Plugin	Variable	Required	Notes
memory	MEMORY_MCP_URL	Yes	Must be a valid HTTP(S) URL.
memory	MEMORY_ENGINE_URL	Yes	Must be a valid HTTP(S) URL.
firecrawl	FIRECRAWL_MCP_URL	Yes	Must be a valid HTTP(S) URL.
domain-indexer	DOMAIN_INDEXER_URL	No	URL override; otherwise resolved from NETWORK.
composio	COMPOSIO_API_KEY	Yes (when loaded)
composio	COMPOSIO_BASE_URL	No	Defaults to https://composio.ixo.earth.
sandbox	SANDBOX_MCP_URL	Yes	Must be a valid URL.
skills	SKILLS_CAPSULES_BASE_URL	No	URL. Defaults to https://capsules.skills.ixo.earth.
slack	SLACK_BOT_OAUTH_TOKEN	Yes	Triggers autoDetect.
slack	SLACK_APP_TOKEN	No
slack	SLACK_USE_SOCKET_MODE	No	Defaults to 'true'.
slack	SLACK_MAX_RECONNECT_ATTEMPTS	No	Coerced to number; default 10.
slack	SLACK_RECONNECT_DELAY_MS	No	Coerced to number; default 1000.
credits	SUBSCRIPTION_URL	No	URL.
credits	SUBSCRIPTION_ORACLE_MCP_URL	No	URL.
credits	DISABLE_CREDITS	No	Enum — exactly 'true' or 'false' (any other value fails env validation). 'true' disables the credit-enforcement middleware; the plugin’s autoDetect also excludes the whole plugin when DISABLE_CREDITS=true.
tasks	REDIS_URL	Yes (when loaded)	Triggers autoDetect.
tasks	TASKS_MAX_PER_USER	No	Coerced positive int; default 50. Max scheduled tasks per user.
tasks	TASKS_RUN_LOCK_TTL_SEC	No	Coerced positive int; default 600. Per-run lock TTL (seconds).
tasks	TASKS_MIN_CRON_INTERVAL_SEC	No	Coerced positive int; default 300. Minimum allowed cron interval (seconds).
matrix-group-chats	CHANNEL_MEMORY_SYNC_INTERVAL_MS	No	Coerced int, min 1000; default 60000. Debounce window between a write and the Matrix snapshot upload.
matrix-group-chats	GROUP_CHAT_ACTIVE_THREAD_TTL_MS	No	Coerced int, min 60000; default 1800000. How long a thread stays “active with the bot” after a reply.
matrix-group-chats	GROUP_CHAT_REQUIRE_POWER_LEVEL	No	Coerced int, min 0; default 0. Extra minimum power level the bot must have before posting (0 = use the room default).
matrix-group-chats	GROUP_CHAT_ROOM_INFO_TTL_MS	No	Coerced int, min 60000; default 1800000. How long roomInfo (membership, DM flag) stays cached.

Variables read but not owned

Some plugins read variables that live in another schema:

• composio reads the core NETWORK and forwards it as x-ixo-network.
• skills reads NETWORK and forwards as X-IXO-Network.
• sandbox reads ORACLE_SECRETS (core) and SKILLS_CAPSULES_BASE_URL (owned by skills) and forwards them as headers.

These are declared in the plugin’s sibling schemas (typed optional()); a missing value just skips the matching header instead of failing the plugin build.

Generating an .env template

qiforge-cli env generates a .env template for your installed plugin set. Until that lands, write the file by hand using this reference.

Related references

• Plugin catalog — env vars per plugin in catalog form.
• Plugin config and env guide — declaring your own plugin’s vars.