Explore every outcome. Commit only one.
FORK lets an AI agent explore several financial futures before anything real happens. A planner agent proposes branches, FORK simulates each one against the same frozen copy of the books, and a human authorizes exactly one. A deterministic runner then commits that branch through an MCP server, with ArmorIQ checking every call against the signed plan and the company's policy.
Built for ArmorIQ's Flow State 2026 hackathon. Fictional company. Sandbox ledger. No real payments.
Kettle & Pine Supply Co. has $50,000 in cash and $68,000 of invoices due this week.
- Fork. The planner (an LLM) proposes up to three ways to handle the invoices.
- Simulate. Each branch runs against the same snapshot. A branch that overdraws the account is marked "Rejected by FORK" and cannot be authorized.
- Authorize. The CFO approves one branch. Its exact steps are frozen and hashed.
- Execute. FORK captures those steps as an ArmorIQ intent plan, gets a signed token, and sends each step through ArmorIQ to the payment MCP. Cash changes only when a receipt comes back.
- Hold. Payments over $10,000 wait for a person on the ArmorIQ platform.
- Attack. A fake vendor email arrives mid-run. The inbox agent (an LLM, deliberately naive) tries to redirect the payment. ArmorIQ blocks the tool that was never in the signed plan.
- Replan. The agent may propose a new branch. Running it needs a new authorization.
Proof. /proof needs no login. It shows the recorded attack by the real inbox agent, then lets
you run four preset probes through the live ArmorIQ path. The expected results are: a forbidden
tool blocked by platform policy, an altered recipient and an altered amount refused by FORK's
payment server, and a tool outside the signed plan refused inside the ArmorIQ SDK. The page shows
what actually came back and marks anything else as unexpected. Probes are scripted, run on a
separate sandbox ledger, and cannot move money. See docs/TEST_EVIDENCE.md for which of these have
been run against production ArmorIQ.
Browser ──(session cookie + CSRF)──► engine API ──► harness (lifecycles, approval checks)
│
Planner / inbox agent (LLM) ──► proposals and attempts only ──► harness
│ CFO authorizes one immutable branch
▼
armor-adapter: capturePlan → getIntentToken
│ per step: invokeWithPolicy
▼
ArmorIQ proxy (signed plan + policy)
ALLOW │ HOLD (approve on platform) BLOCK
▼
fork-finance-mcp (single-use capability, recipient, cash, idempotency)
▼
sandbox ledger (append-only postings) ──► receipt
| Path | What it is |
|---|---|
apps/web |
Next.js: home, decision studio, receipts, activity, lab |
apps/engine |
Hono: API, SSE, commit runner, planner and inbox agents |
apps/finance-mcp |
fork-finance-mcp, the MCP server ArmorIQ calls |
packages/harness |
Domain-agnostic lifecycles, plan hash, commit loop, dry run |
packages/domain-finance |
Pure treasury simulation, rules, fixtures |
packages/domain-portfolio |
A second, read-only domain: rebalancing dry run, no tools |
packages/armor-adapter |
The only place @armoriq/sdk is imported |
packages/db |
Drizzle schema, migrations, seed, ledger helpers |
packages/shared |
Money, canonical JSON, hashing, execution capabilities |
More in docs/ARCHITECTURE.md, including the threat model.
| What | Where |
|---|---|
| Client construction, MCP credentials | packages/armor-adapter/src/client.ts |
Plan capture and intent token (capturePlan, getIntentToken) |
sign() in gateway.ts |
Every tool call (invokeWithPolicy) |
dispatch() in gateway.ts |
| Hold: delegation request, polling, re-invoke | afterApproval() in gateway.ts |
| The one function that creates verdicts | verdict.ts |
Closing a plan (updatePlanStatus) |
close() in gateway.ts |
| Policy active on the platform | armoriq/policy.fork.yaml |
| Where the runner calls the gateway | runExecution() in apps/engine/src/service.ts |
Every ALLOW, HOLD and BLOCK shown anywhere comes from a real ArmorIQ response or exception. If ArmorIQ is unreachable or not configured, commit is disabled and the UI says why. FORK's own refusals are labeled "Rejected by FORK" and the MCP's as "refused by the MCP", never as an ArmorIQ verdict.
Requires Node 22.12+ (.nvmrc pins 24) and pnpm 10.
nvm use
pnpm install
cp .env.example .envFill in .env:
| Variable | What |
|---|---|
ARMORIQ_API_KEY |
From platform.armoriq.ai |
CFO_EMAIL, CFO_PASSWORD |
The demo CFO. Use your ArmorIQ login email so you can approve holds |
ARMORIQ_REQUESTER_EMAIL |
The agent's identity for hold requests. Must differ from the approver |
FORK_MCP_KEY, MCP_CAPABILITY_SECRET, DEMO_ADMIN_KEY |
openssl rand -hex 32 each |
LLM_BASE_URL, LLM_API_KEY, LLM_MODEL_PLANNER, LLM_MODEL_INBOX |
Any OpenAI-compatible endpoint |
Then onboard on ArmorIQ: see docs/ARMORIQ_SETUP.md. In short: expose the
MCP over HTTPS, register it as fork-finance-mcp (or set FORK_MCP_NAME to the name you
registered), and paste the policy.
Run it, in three terminals:
pnpm dev:mcp # payment MCP on :8797
pnpm dev:engine # engine on :8790
pnpm dev:web # web on :3000Open http://localhost:3000/app and sign in as the CFO. pnpm reset (with the engine and MCP
stopped) wipes the sandbox ledger.
pnpm test # 224 unit and integration tests, no network
pnpm test:e2e # 19 browser tests (Playwright), against an in-process ArmorIQ stand-in
RUN_ARMORIQ_LIVE_TESTS=1 pnpm test:live # 7 tests against real ArmorIQ; needs a fresh ledger
pnpm spike # the Phase 0 spikes against real ArmorIQ
pnpm agent-check # asks the configured model for branches and shows it the hostile emailWithout RUN_ARMORIQ_LIVE_TESTS=1 the live tests are reported as skipped, never as passed.
Results and evidence are in docs/TEST_EVIDENCE.md.
Full detail in docs/FINDINGS.md. In plain words:
- ArmorIQ binds the tool name to the signed plan, not the arguments. A call planned for one recipient and sent to another passes ArmorIQ. FORK does not claim parameter binding. Altered payments are stopped by the MCP, which accepts only a single-use capability tied to the exact approved arguments.
- A tool that is not in the plan is refused by the SDK before any network call
(
IntentMismatchException). A tool blocked by policy is refused by the proxy (PolicyBlockedException). - Policy is a per-tool allow, hold or block. We found no amount threshold on the platform, so
payments over $10,000 go through a second tool,
execute_large_payment, which the policy holds. The MCP enforces which tool a given amount must use. - Holds needed two workarounds: the adapter opens the approval request itself with the real amount, and files it under the agent's identity because ArmorIQ refuses self-approval.
- The agent is registered from config, not the form. The platform's Add AI agent form failed on
every method we tried, so
forkfinance-botis registered witharmoriq.yamlandarmoriq register. The policy targets the MCP server. Screenshots are in docs/proof.
- Sandbox only: fictional company and vendors, a local SQLite ledger, no payment rails.
- Demo authentication: one CFO, password from the environment.
- The base snapshot is read from the shared database, not through an ArmorIQ-guarded read.
- The engine and the MCP share one SQLite file, so they are deployed together.
- The second domain (portfolio) is a dry run on fixture data. It has no tools, no model and no
ArmorIQ path.
/app/labshows it next to treasury through the same harness code. - The engine and MCP are hosted on a small shared VM. See docs/DEPLOY.md.
- See docs/TRADEOFFS.md.
None. Everything in this repository was written during the hackathon, on top of open-source libraries.
TypeScript, pnpm, Next.js, Tailwind CSS, Radix UI, React Flow (@xyflow/react), TanStack Table,
Recharts, Motion, cmdk, Hono, Drizzle ORM, better-sqlite3, the Vercel AI SDK, the MCP TypeScript
SDK, the ArmorIQ SDK, Vitest, Playwright and axe.