Canary
Documentation
How to install, operate, and understand Canary against your own Interactive Brokers account. Start at the top if Canary is new to you; later sections move closer to the code.
Start
Install Canary, point it at a gateway and an MCP host, and confirm the desk is live.
- Install and first runPrerequisites, the install paths, and the first commands that prove the gateway is reachable.
- Connect an MCP hostWiring Claude Desktop, Claude Code, Cursor, and Zed to the local server, and checking the connection.
- Your first sessionA guided half hour: read the account, quote a symbol, run a brief, and interpret what comes back.
- UpdatingUpdate the binary, the Desktop extension, S&P 500 membership, calendars, and local process state.
- TroubleshootingGateway not reachable, stale quotes, a daemon that will not start, and the logs that answer each one.
Operate
The daily loop: briefs, agent sessions, the paired app, order previews, protection, and reconciliation.
- The daily deskA working routine from the morning brief through regime, stress, and rules to the end-of-day read.
- Working with agentsWorkflows, limits, and worked examples for driving Canary from an MCP host.
- The paired appRunning canary app, pairing a phone, the event stream, and opt-in push notifications.
- Alerts and notificationsWhat raises an alert, where it is delivered, how delivery is proven, and how to tune the noise down.
- Order previews and the trading buildThe read-only default, what an order preview does and does not do, and the separate opt-in trading build.
- Protection and emergency exitsTrailing-stop and risk-reduction proposals, per-row blockers, and what purge and restore actually do.
- ReconciliationMatching broker statement flows against the declared capital ledger, and handling the lines that will not match.
Understand
What the numbers measure, when they can be trusted, and who sets the limits they are measured against.
- ConceptsCalendars, regime, stress, market events, protective stops, gamma, and breadth in one mental model.
- SensorsHow each measurement establishes authority and freshness, and how a gap fails closed instead of guessing.
- Trading policyWho decides the risk boundaries, what the daemon evaluates, and what never becomes submit authority.
- The rulebookThe fourteen advisory rules, what each one is protecting against, and how a breach is reported.
- Writing a risk policyTurning a personal risk mandate into the policy file: limits, drawdown ladder, overrides, and review.
- Market data and entitlementsWhich subscriptions produce real-time data, what delayed and frozen mean, and how freshness is reported.
- GlossaryOne place for the terms the other pages assume: NLV, R-multiple, zero gamma, last-good, fingerprint.
Reference
Command, tool, and configuration lookups. Most of this is generated from the code it documents.
- CLIEvery Canary subcommand with its flags and usage, generated from the command registry in the binary.
- MCP toolsEvery tool exposed by canary mcp, with parameters and invocation guidance. Generated from the registry.
- MCP resourcesThe non-tool resources, including the live quote subscription URI template.
- ConfigurationTOML configuration, policy files, runtime platform settings, and environment variables.
- Releases and supportVersion scheme, what a release contains, how signatures are verified, and which versions are supported.
Under the hood
For readers who want the design: processes, typed contracts, storage, the wire protocol, and packaging.
- ArchitectureRuntime processes, typed contracts, external data flows, state ownership, and deployment boundaries.
- StorageWhy the daemon uses SQLite, how the data model follows from its job, and how state survives a restart.
- TWS wire protocolCoverage and semantic fingerprints for the clean-room Go implementation of the TWS protocol.
- Regime dashboard contractSource quality, cluster logic, lifecycle decisions, and the backtest that has to pass before a change ships.
- Regime and stress backtest runbookHow the regime and stress lifecycle is proven and tuned against point-in-time evidence.
- Opportunity research harnessThe diagnostic harness for testing candidate strategies against point-in-time evidence before trusting them.
- Gamma cache persistenceDesign and invalidation semantics for the daemon's persistent dealer zero-gamma cache.
- Packaging and distributionWhat each published artifact contains, how it is signed, and the boundary every channel ships with.