Modes & flags

operator

Every runtime mode, its env flag, its default, and what it takes to enable.

Operator documentation. This page is for HISS operators and is excluded from the public docs navigation and search indexing.

The mode matrix

Every runtime behavior is governed by an explicit flag with a safe default: everything dangerous is off, everything mock is on. The table below is the operator's map; GET /api/health reports the live values.

Mode	Env flag	Default	What it controls
Paper / mock (current public)	NEXT_PUBLIC_ENABLE_MOCKS (mock AI + oracles)	on	Deterministic mock strategist and mock oracle prices. Everything simulated, zero keys required.
Registry-readonly	— (always on)	on	The canonical asset registry and validation rules apply in every mode; there is no flag to bypass them.
Bankr-enabled strategy	AI_PROVIDER + BANKR_API_KEY (server-only)	bankr_or_mock, no key → mock	Bankr answers whispers when a key is configured; graceful mock fallback otherwise. Planning only.
x402 mock	NEXT_PUBLIC_ENABLE_X402	off → free mock envelopes	Paid endpoints answer for free, labeled cacheStatus "mock". The current public behavior.
x402 verified	NEXT_PUBLIC_ENABLE_X402 + Bankr facilitator verification	not yet available	Real settlement verification with replay protection. Not enabled anywhere until verification ships.
Live pricing gate	— (code-level, not a flag)	structurally closed	assertLivePricingAllowed() throws on every live-pricing path until the chain-4663 sequencer uptime feed is published and pinned. No flag can open it.
Pinned Chainlink feeds	— (feedRegistry.ts, audited in CI)	26/27 pinned (BE has no published feed)	Feed proxies pinned 2026-07-06 from Chainlink's directory and live-verified. Pins are a precondition for live pricing, not an activation.
Live execution	NEXT_PUBLIC_ENABLE_LIVE_ONCHAIN	off	On-chain execution paths. Stays off until the live pricing gate opens and contracts are audited.
Vault deposits	NEXT_PUBLIC_ENABLE_VAULTS	off	ERC-4626-style vault deposits (unaudited beta). Off in every public build.
MCP planning surfaces	NEXT_PUBLIC_ENABLE_MCP_MODE	on	Shows MCP export UI. Exports are text plans only; see MCP export docs.

Coil execution modes

Separate from the runtime flags above, every Coil carries one of four execution modes — safest first, and the default is always paper_only:

Mode	Default	Capsule	What it means
paper_only	yes — always	refused	Simulation and analysis only. Runbook + share card compile; capsules do not.
preview_only	—	compiles	Analyze and propose only — the capsule forbids placing, modifying, or canceling anything.
human_confirm	—	compiles	Simulate-first; each order presented for explicit per-order approval, ticker and dollar amount echoed back.
agentic_mcp_enabled	—	compiles only with the ack flag	Requires the explicit userAcknowledgedAgenticMode flag at compile time — a mode string alone never unlocks it. Fuses stay binding; the user monitors and owns every trade.

Every non-paper capsule is written simulate-first: Robinhood’s Trading MCP exposes simulate-order and verify-tradability tools, and the capsule’s session protocol runs them before anything else. Details: Execution Capsules.

The rule for dangerous flows

Nothing dangerous turns on by accident. Live execution, vault deposits, and verified x402 settlement each require an explicit flag flip and production credentials — and the flags alone are not sufficient: live valuation also needs the code-level gate open (feed proxies are pinned for 26 of 27 assets, but the sequencer uptime feed for chain 4663 is unpublished, so the gate stays structurally closed), and x402 verified mode needs Bankr facilitator settlement verification plus replay protection. Absent those, the flags degrade to safe behavior rather than half-enabled danger.

Operator workflow: the audit scripts

Three guardrail scripts keep the pinned data honest. Run them from the repo root on every audit cycle (and before any change to the registry or feed pins):

pnpm audit:robinhood-registry — diffs the canonical asset registry against the official contracts page and the live explorer.
pnpm audit:chainlink-feeds — checks the pinned feed proxies for drift against Chainlink's published data, and re-polls for the missing BE and sequencer uptime feeds.
pnpm audit:robinhood-docs — compares the hashed official docs snapshot against the live pages, flagging any upstream changes to re-audit.

Flag aliases exist for convenience (NEXT_PUBLIC_ENABLE_LIVE_TRADING, NEXT_PUBLIC_ENABLE_VAULT_DEPOSITS, and the mock umbrella NEXT_PUBLIC_ENABLE_MOCKS); the first set value wins.
Mock switches can also be set individually: NEXT_PUBLIC_MOCK_AI and NEXT_PUBLIC_MOCK_ORACLES.
Server-only secrets (BANKR_API_KEY and friends) never use the NEXT_PUBLIC_ prefix — see Bankr integration.