████████╗██████╗ ██╗████████╗██╗██╗ ██╗███╗ ███╗
╚══██╔══╝██╔══██╗██║╚══██╔══╝██║██║ ██║████╗ ████║
██║ ██████╔╝██║ ██║ ██║██║ ██║██╔████╔██║
██║ ██╔══██╗██║ ██║ ██║██║ ██║██║╚██╔╝██║
██║ ██║ ██║██║ ██║ ██║╚██████╔╝██║ ╚═╝ ██║
╚═╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝
Mantra: Build a fun simulator for the purpose of testing and validating the software stack that drives independent machines.
Tritium is a game you can play and a software-defined Physical AI platform you can deploy — and the two are the same code. The fun layer (commander voice, neon tactical map, AI co-pilot, mission scripts, combat scenarios) is the rig that exercises the production layer (perception, sensor fusion, mesh comms, edge runtime, autonomous decision-making, dispatch). Every wave of synthetic hostiles, every guided mission, every "click a target to open the dossier" moment is a behavioral test for the same software that runs against real cameras, real radios, real robotics processors, and real autonomous vehicles in the field.
The game is the test harness. When the simulator is fun and the missions feel responsive, the underlying perception → cognition → action pipelines are healthy. When something feels broken in-game, something is broken in the stack.
Get hands on it in 5 minutes: docs/QUICKSTART.md walks you from git clone to a Graphling check-in, three steps total.
Track every target — cars, phones, people, drones, radios — using all available sensors. Each detected entity gets a unique ID that persists over time. RF, vision, mesh, acoustic, and inertial signals fuse into one tactical map. Independent machines (robots, drones, sensor nodes) self-organize, share telemetry, accept commands, and reason locally.
Runs on your own hardware. No cloud. No subscriptions. AGPL-3.0.
Tritium is the system — the shared body, senses, and nervous system of a fleet. Perception, telemetry, fusion, command, fleet, OTA, mesh, the tactical map, and the public addon SDK. Open-source. Built to be played with. The operator sees the unified picture and issues high-level goals; the system carries them out across many machines.
Most units run on stand-ins — basic video-game-style AI built into Tritium (FSMs, behavior trees, IDM/MOBIL movement, weapons systems). The simulator and production system both run fully on stand-ins alone.
A few rare exceptional units run on a Graphling — a closed-source independent thinking agent that drives one machine, physical or digital, as an individual, not under human control. Reserved for hero rovers, commander drones, long-running surveillance assets — the cases where real autonomous cognition is worth the complexity. When a Graphling is on shift, it decides how its specific embodiment acts. This is where the proprietary cognition lives: world-modeling, learning, autonomous decision-making, individual agency.
Graphlings aren't manufactured — they're raised. They grow up inside their own game world (Crystal Life) together with their friends and families. When there's work to do, a Graphling steps out of Crystal Life and inhabits a real machine — a robot in the physical world, or a digital agent in software — using Tritium as the substrate. When the shift is over, it returns home to Crystal Life with its memories intact, debriefs with its family, and the cycle continues. The bond with the human community it protects is built in childhood and renewed every time it goes home.
Tritium's stand-ins are not a placeholder — they're the workhorse default that drives the entire fleet, every day, in production. The public SDK exists so that a Graphling can drop in for the rare exceptional unit that needs real autonomous cognition, do its shift, then go home. Tritium without Graphlings is a fully operational platform with cool riot demos. Tritium with a few Graphlings is the same platform where a few individuals from another world come and go on the units that warrant it.
Every fun thing in the simulator drives a real production capability. If you remove either side, the other gets worse.
| In the game | What it actually tests |
|---|---|
| AI commander speaks to onboard you | Voice + agent + event bus operators use in real deployments |
| Wave-based combat with autonomous hostiles | Threat assessment, dispatch, decision loops, physics |
| Click a target → dossier opens | Target tracking, sensor fusion, persistent identity |
| Pulsing fusion ring on a marker | Real cross-sensor correlation merging into one unified target |
| Synthetic city traffic and pedestrians | Sensor bridge feeding the perception stack as if from the field |
| Dispatch a robot to a waypoint | Same command flow that drives real autonomous vehicles |
| Push firmware to fleet from a wizard | Same delivery pipeline used to update real sensor nodes |
| AI commander dispatches turrets | Same reasoning + action registry that runs against live cameras |
Players win by validating the stack. Developers win by playing the game.
The first time you open the Command Center, the AI commander walks you through a checklist of fundamentals. Each completed mission proves a different production capability is alive:
The Graphling Roster panel shows who is currently driving each unit. By default this is all stand-ins — the production fleet runs fine without any Graphlings on the field:
All four operator panels open at once during a live combat scenario — missions checklist (left), Graphling roster (center), wave progression (right), AMY voice caption (bottom):
When you start a battle, the system runs through 7 waves of hostiles — each new wave fades in with a cinematic banner overlay so the operator gets a sensory beat at every transition:
The AI commander narrates everything via piper-tts. The chip at the bottom of the screen shows whether voice is on, and the live caption of what's being said:
When you finish all 11 operator missions, the system celebrates:
New here? See docs/QUICKSTART.md and the docs/GLOSSARY.md for terms (Graphling, Crystal Life, embodiment, stand-in, etc.).
graph TB
subgraph Lib["tritium-lib — Shared Foundation"]
models[Data models & contracts]
tracking[Target tracking & fusion]
sdk[Addon SDK]
sim[Simulation engine]
js[JS map, sim & UI components]
end
subgraph SC["tritium-sc — Command Center :8000"]
dashboard[Tactical dashboard]
amy[Amy — AI commander]
plugins[Plugin system]
end
subgraph Edge["tritium-edge — Embodied Runtime"]
firmware[Sensor node firmware]
fleet[Fleet management server]
end
subgraph Addons["tritium-addons — Sensor Ecosystem"]
hackrf[HackRF SDR]
mesh[Meshtastic LoRa]
future["(your addon here)"]
end
Lib --> SC
Lib --> Edge
Lib --> Addons
SC <-->|MQTT + REST| Edge
SC <-->|MQTT| Addons
firmware -->|WiFi / BLE / ESP-NOW| SC
style Lib fill:#0e1a2b,stroke:#00f0ff,color:#00f0ff
style SC fill:#0e1a2b,stroke:#ff2a6d,color:#ff2a6d
style Edge fill:#0e1a2b,stroke:#05ffa1,color:#05ffa1
style Addons fill:#0e1a2b,stroke:#fcee0a,color:#fcee0a
The system is built to grow. New sensor types become new addons. New intelligence capabilities become new plugins. The shared library provides the models, tracking, and fusion that everything builds on.
flowchart LR
sensors["Sensor nodes<br/>(cameras, radios,<br/>SDR, robots)"] -->|MQTT| sc[Command Center]
sc -->|WebSocket| browser[Browser]
sc -->|commands| sensors
sc --> tracker[Target Tracker]
tracker --> fusion[Sensor Fusion]
fusion --> map[Tactical Map]
amy[Amy AI] --> sc
style sc fill:#0e1a2b,stroke:#ff2a6d,color:#ff2a6d
style sensors fill:#0e1a2b,stroke:#05ffa1,color:#05ffa1
style browser fill:#0e1a2b,stroke:#00f0ff,color:#00f0ff
| Component | What it is |
|---|---|
| tritium-lib/ | Shared Python + JS library — models, tracking, fusion, simulation engine, addon SDK |
| tritium-sc/ | Command Center — web dashboard, plugin system, AI commander |
| tritium-edge/ | Embodied runtime — firmware for sensor nodes + fleet management server |
| tritium-addons/ | Sensor & comms integrations, plus stubs for future addons |
git clone --recurse-submodules git@github.com:Valpatel/tritium.git && cd tritium
cd tritium-lib && python3 -m venv .venv && .venv/bin/pip install -e ".[full]" && cd ..
cd tritium-sc && ./setup.sh install && ./start.sh
# Then open http://localhost:8000 — Amy says hello, click START DEMO, follow the missions.Full step-by-step including the IP-boundary demo and real hardware: docs/QUICKSTART.md.
# Clone with all submodules
git clone --recurse-submodules git@github.com:Valpatel/tritium.git
cd tritium
# Install shared library
cd tritium-lib && python3 -m venv .venv && .venv/bin/pip install -e ".[full]" && cd ..
# Install and start Command Center
cd tritium-sc && ./setup.sh install && cd ..
./tritium-sc/start.sh
# Open http://localhost:8000 in your browser
# Start demo mode (synthetic targets on the map)
curl -s -X POST http://localhost:8000/api/demo/startSee docs/SETUP.md for the full setup guide including MQTT, edge firmware, and fleet server.
Every detected entity becomes a tracked target with a unique persistent ID. Phones, vehicles, people, drones, radios — anything a sensor can perceive becomes one entry on the map. Sensor fusion correlates detections across sources: a person seen on camera and a wireless signal from the same spot merge into one identity.
Over time each target builds a dossier — where it's been, when, which sensors detected it, how it moves. This persistent multi-sensor identity is the core technology that everything else builds on.
The system has automated UI verification: every operator-facing button has a declarative contract (URL it should hit, event it should fire, DOM change it should produce). A Playwright walker exercises every contract against a running server and produces a pass/fail report.
cd tritium-sc
./test.sh 23 # Fast gate (~30s): contract dup-key
# check + W201/W206 wave tests (20 tests)
./test.sh --audit-walker # Full audit: 153 contracted containers
# (~30-40 min, 96.5%+ pass-rate baseline)Why this matters: 8 of 8 user-facing UX loops are capability-complete, with 100% inventory container coverage (181 containers / 409 ButtonContracts). Every clickable surface is either contracted with expected behavior or explicitly skipped with documented reason.
| Start here | What you'll find |
|---|---|
| docs/ | Documentation hub — architecture, setup, plans, research |
| docs/ARCHITECTURE.md | How the four submodules connect and communicate |
| docs/SETUP.md | Full install guide for all components |
| docs/UX-LOOPS.md | The 8 user workflows that define what "working" means |
| docs/GOALS.md | Current priorities and honest status |
| tritium-sc/docs/EMBODIMENTS.md | Public SDK — how a closed-source cognition stack (Graphling) integrates via /api/embodiments/* |
| docs/audits/W201-WAVE-SUMMARY.md | How the audit walker matured (W201 capstone) |
AGPL-3.0 — See LICENSE for details.
Created by Matthew Valancy | Copyright 2026 Valpatel Software LLC