Radon
Market-structure reconstruction. Radon surfaces convex options trades from dark pool and OTC flow, the volatility surface, and cross-asset positioning. Every candidate runs a hard three-gate framework before sizing.
Flow signal or nothing. No narrative trades, no chart-pattern trades.
Contents
What it does
- Detects institutional positioning through Interactive Brokers, Unusual Whales, MenthorQ CTA, and cross-asset feeds.
- Designs convex options structures and sizes them with fractional Kelly.
- Streams live quotes, greeks, P&L, and order state to a Next.js terminal at
localhost:3000 (laptop dev) and app.radon.run (production).
- Auto-deploys to a Hetzner VPS on every push to
main.
Three gates, in order
| Gate | Rule |
|---|
| Convexity | Potential gain >= 2x potential loss. Defined-risk default. |
| Edge | Specific, data-backed signal that has not fully moved price. |
| Risk | Half Kelly (0.5) default, 0.25 optional stricter, full Kelly banned. Hard cap 2.5% of bankroll per position. |
Any gate fails, no trade. Full rules in CLAUDE.md. Strategy specs in docs/strategies.md.
Quick start
Prerequisites
git clone https://github.com/joemccann/radon.git
cd radon
cp .env.example .env # then fill in
cp web/.env.example web/.env # then fill in
pip install -r requirements.txt
cd web && bun install && cd ..
The two .env.example files are the canonical variable reference. Read those before the operations runbook.
Dev launchers
scripts/cloud.sh # laptop = Next.js attached to the VPS (FastAPI, IB relay, headlines)
The launcher never starts a Gateway, collector or scheduler; the env contract
and prerequisites are in the attach contract.
Open http://localhost:3000 and sign in with Clerk; the operator id must be in ALLOWED_USER_IDS in web/.env.
Architecture at a glance
Private CI and operator access, the app/broker private connection, recovery-only public SSH, and the isolated demo. Firewall labels are generated from the checked-in rule files. Regenerate with python3 tools/render_network_topology.py; verify with --check. The host-split owner explains the paths; operations owns live rollout and recovery.
Unusual Whales ─┐
Interactive Brokers ├──> Signal Detection ──> Strategy Evaluation
MenthorQ ──┘ │
▼
Convex Structure Builder
│
▼
Kelly Position Sizing
│
▼
Execution / Monitoring
│
▼
Radon Terminal
Process layout
localhost:3000 for the Next.js 16 terminal:8321 for FastAPI (JWT-gated, localhost bypass for server-to-server):8765 for the IB realtime WebSocket relay- 120s loop for the newsfeed scraper (headless Playwright)
Storage
- Turso libSQL cloud DB (canonical). Direct-to-cloud. Embedded replica retired 2026-05-20. See
docs/cloud-services.md.
- JSON files in
data/ as fallback / DR archive
- Hetzner-hosted
media.radon.run for newsfeed images
Developer runbook: CLAUDE.md.
Now true
Durable facts. History and mechanism live in the owner file, not here.
- Indicators. Regime tabs at
/regime/{skew,skew2d,straddle,cor,curve}. Cheap-wing scanner at /scanner?mode=vol-cone. Specs: docs/indicators/.
- CMD+J. Quotes, priced UW chains, and
evaluate.py run from the in-app assistant. KB miss is not a dead end.
- Orders. Desktop/mobile tickets support
STP and STP LMT. In the Position tab, select put/call legs and choose Close Selected Legs to close a spread or cover a short leg; review retained legs before confirming.
- Incidents. Watchdog artifacts under
data/incidents/. Triage with /incident <path>. Cases: docs/incident-runbook.md.
- Research dates. Dropbox PDF report dates stay on the text ladder unless
CLAIRIC_DATES_ENABLED=1. Contract: docs/dropbox-research.md.
Project layout
radon/
├─ scripts/ Python scanners, evaluators, broker integrations
│ ├─ clients/ Broker and data-provider adapters
│ ├─ api/ FastAPI (:8321)
│ ├─ monitor_daemon/ Background fill/exit/rebalance daemon
│ ├─ db/ Turso writers + migrations
│ ├─ knowledge/ radon-kb MCP (journal, evals, incidents)
│ └─ watchdog/ Service-health alerting
├─ web/ Next.js 16 terminal (bun)
├─ site/ Marketing site (npm, separate Vercel project)
├─ cloud/ VPS systemd, Caddy, deploy, IB Gateway compose
├─ lib/tools/ Pi tools (Vitest + CI)
├─ tests/ TWR money-math (CI collects this directory)
├─ docs/ Topic-scoped documentation (index: docs/README.md)
├─ config/ Laptop/mini ops launchd plists (codemap, external probe, grok, incident responder, fx; no collectors)
├─ brand/ Design system and tokens
└─ CLAUDE.md Authoritative developer runbook
Documentation
Index: docs/README.md. External services: docs/external-services.md. Equibles: docs/equibles-api.md. Toolchain map: DEVELOPMENT.md.
Data source priority
Follow the source priority and subsystem requirements in
docs/external-services.md. Research and news
sources do not substitute for missing market data.
Deployment
Merging a reviewed pull request into main triggers the deploy. After the CI gates pass, GitHub Actions extracts cloud/ from the exact tested SHA into an immutable VPS runner and runs its deploy contract.
Canonical infra: cloud/. Recovery: cloud/CLAUDE.md and docs/monorepo-cloud-migration.md. Confirm: gh run list --workflow=ci.yml --limit 1.
Tests
python3.13 scripts/run_pytest_affected.py # scoped Python tests
python -m pytest scripts/tests/ -v # full Python suite
cd web && bun test # Vitest
cd web && bunx playwright test # E2E
Mocked API calls cover most of the surface. Order-route integration uses an isolated test-mode FastAPI harness (web/tests/fastapiHarness.ts) that never reuses the broker-backed localhost:8321 server.
The isolated TesterArmy flow suites run the workstation and public-site journeys with version-locked browser engines and retain reports and screenshots in CI.
Maintainers and help
Maintained by Joe McCann. Single operator. Clones are unsupported. See SUPPORT.md.
Security reports: SECURITY.md. Do not open a public issue for a vulnerability.
License
Dual-licensed under either of
at your option. SPDX-License-Identifier: Apache-2.0 OR MIT
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
