Run it again.
Seedable simulation and deterministic components help teams compare behavior under the same conditions. Repeatability is an aid to inspection, not proof of real-world correctness.
00 / Premise
Make the system legible before making it powerful.
Gygax brings the pieces of an autonomous system into one C++26 project: an agent runtime, a service, physical and simulated interfaces, and research tools. It is a toolkit for building and evaluating systems. It is not a promise that autonomy is safe by default.
Use defined interfaces.
Agents call tools. Devices use protocols. Modules and SDKs provide extension points. Keep model decisions separate from the interfaces that carry them out.
Make authority a choice.
Device command access is disabled by default. Service networking, authentication, and physical safeguards remain deployment decisions that must be made deliberately.
“God does not play dice with the universe.”ATTRIBUTED TO ALBERT EINSTEIN · THEME, NOT A PROJECT CLAIM
01 / First run
Build it. Check it. Then decide what to trust.
Linux with Clang 18+ is the reference platform. The quick start builds the project and runs its in-process diagnostic suite before you connect a model or a device.
01 · source build · Linux
git clone https://github.com/magneato/gygax
cd gygax
./setup.sh # check prerequisites
./build.sh # compile into ./build
./build/gygax doctor # in-process self-testsStart with echo
Bring up the API without a remote model. The built-in echo engine is useful for smoke testing and learning the endpoints.
./build/gygax serve --engine echo
./build/gygax statusTry a network
Build the library, point the Python bindings at it, then run the included STDP example.
export GYGAX_LIB=$PWD/build/libgygax_c.so
export PYTHONPATH=$PWD/python
python3 examples/python/stdp_demo.pyWindows 11 users should use the documented Docker Desktop / WSL2 workflow. See Windows setup. Production installation options are in Operations.
02 / System map
One runtime. Several layers that can meet.
The architecture separates inference, agent orchestration, tools, embodiment, simulation, and transport. Connect the layers your use case needs; nothing requires every installation to control hardware.
ARCHITECTURE / SIMPLIFIEDFull architecture ↗
chat API / Ollama API ─── service ─── inference pool ─── model backends
│ │
│ orchestrator ─── agents ─── registered tools
│ │ │
metrics / auth world model / events devices / logistics
│
simulation ── robot links ── transports
│ │
LiDAR / USD MAVLink / CAN / ROS
│
neuromorphic engine ── C ABI ── PythonFor module ownership, threading, the agent loop, extension points, and deliberate limits, read Architecture.
03 / Capabilities
What ships in the repository.
Gygax is broad by design. The capabilities below describe included source and examples; production readiness depends on each deployment, target, and safety case.
Inference service and routing
HTTP service with standard chat-completions and Ollama endpoints, model-aware routing, engine health probing, failover, optional peers, JSON-RPC, metrics, and graceful shutdown. Built-in echo works without a model server.
Tool-using agent runtime
Objective-driven agent loops with tool calls, episodic memory, step limits, cancellation, worker pools, and event publication. Tools can be registered in-process, supplied by plugins/extensions, or exposed over MCP.
Embodiment and runtime state
Hardware-style node trees, capability aggregation, hierarchical state machines, sensors, actuators, a message hub, temporal buffering, and embodiment taxonomy provide a common model for connected systems.
Simulation and sim-to-real links
A 2D differential-drive world with collisions and LiDAR, UDP/TCP robot links, trajectory export to USD, and vectorized environments for repeatable experiments.
Quantum adapter interfaces
Vendor-neutral contracts for navigation estimates and QKD-backed authenticated secure channels. These are integration interfaces only: no quantum sensor driver, QKD provider, or cryptographic implementation is included. The Seek & Find replay's sensor and basis-sifting values are classical mock data.
Neuromorphic computing
LIF and Izhikevich populations, Poisson and spike-source populations, delayed sparse projections, seeded RNG, and pair-based STDP. Access the engine through C++, JSON/HTTP, the C ABI, and Python bindings.
Robotics and industrial protocols
MAVLink v1/v2, virtual autopilot, SocketCAN and CAN FD, ISO-TP, OBD-II, J1939, DBC, CANopen, Modbus, NMEA 0183, ADS-B, ARINC 429 library support, and rosbridge.
Logistics and supply chain
GUID-tracked entities, append-only ledger events, flow summaries, and range-aware route planning with refuel stops. The API is also available for tools and service integration.
SDKs, transports, and developer tools
C and C++ plugin SDKs, Python bindings and extension SDK, serial, GPIO, modem, printer and G-code transports, plus Gyde, the optional terminal console for inspecting and querying a running node.
Acoustic study (simulation only)
Compare phase-aware tone estimates at explicit 2D observation points and sample synthetic amplitude-modulated alerts. This model has no speaker, audio-output, or flight-control integration; modeled cancellation at one point says nothing conclusive about other locations.
SatLink satellite tracking
Checksum-verified two-line elements, SGP4 and SDP4 that reproduce the reference implementation’s verification output to 0.12 mm, look angles, Doppler from the exact range rate, rise/culminate/set pass prediction, radio retuning through Hamlib rigctld, and SDR reception over rtl_tcp with an FFT spectrum and a Doppler-removing mixer. From C++, the C ABI, Python (with a Skyfield-shaped subset), or gygax track. It never downloads elements; you bring them.
glyder: Gygax in VR
A Gygax world on a map table in a headset: grab, turn and zoom it, then point at a node and ride it at full scale. Natively on Meta Quest (OpenXR on Vulkan, no engine) and in a desktop window. A paired, HMAC-authenticated UDP protocol, head motion rendered locally so it never waits on the network, a code-generated low-poly model kit, and vision correction from a spectacle prescription.
04 / Demonstrations
See the parts work together.
Examples are starting points for inspection and experimentation. They are not operational certification or performance guarantees.
0.4.0 “MATRIX” // SPATIAL COMPUTING & VR
Put on the visor. Take the stick.
glyder drops a running Gygax world straight into your VR headset. Any simulation—or real robotics connected to an embodiment node—materializes on a 3D holographic map table in front of you. Point at any drone, kite, rover, or tank and pull the trigger: you drop in at full 1:1 scale into the cockpit with instant manual controls. Press B to jack out, and the machine's autonomous doctrine seamlessly resumes.
Engineered for maximum presence with zero engine bloat: native OpenXR and Vulkan multiview rendering at 120 Hz on Meta Quest 3S/3/Pro with sub-frame motion prediction and HMAC-authenticated LAN telemetry.
NEURO-ACOUSTIC RADAR
Low-latency AAudio spatial cues panned by bearing and elevation; earcons for node events.
TRITANOPIA GOLD PALETTE
Calibrated warm amber, gold, and jade shaders; zero reliance on blue-only critical cues.
DEAF CUES & HAPTICS
Visual directional subtitle overlays and dual-controller haptic warning pulses.
PRESCRIPTION OPTICS
Hardware IPD matching, prism offset, and directional pre-sharpening along cylinder axes.
./build/ohflock --glyder # live flock defense in VR ./build/wargames --glyder # battlefield command & drone ride ./build/gygax serve --glyder # live robotics node on holo-table
SHOWCASE 01 / WARGAMES
A human-directed agent team
Agents command a bunker, turrets, tanks, and drones. The example composes the orchestrator, tools, collective consensus, a ledger, route planning, and a small LIF-driven hostile hive. The built-in doctrine makes seeded battles reproducible; humans can direct the running simulation.
./build/wargames --map ./build/wargames --interactive ./build/wargames --script examples/wargames/orders.txt
SHOWCASE 02 / ARRIVAL
Simulation meets a robot link
Four rovers traverse a 2D environment with obstacles and LiDAR. One uses a spiking controller; a rover is then promoted over a UDP link to a hardware-style target. The example's far end is an emulator, not a field robot.
./build/arrival ./build/arrival --seconds 30 --real-seconds 5 \ --usd build/arrival.usda
Source: examples/arrival · Simulation docs: Robotics
SHOWCASE 03 / SKYNET · SATLINK
Three passes over Greenwich
An ISS element set, propagated by Gygax’s SGP4 and seen from the Royal Observatory on 1 January 2024. Each track runs horizon to horizon; the curve below is the Doppler shift of a 437.8 MHz downlink from the exact range rate: high as it rises, through zero overhead, low as it sets. Every point on this page was computed by gygax.satlink. Add --live --sdr and an RTL-SDR follows this curve second by second, reporting where the carrier really is.
./build/gygax track --tle examples/satlink/sample.tle \ --at 51.4779,-0.0015,46 --start 2024-01-01T12:00 --downlink 437.8e6
SGP4/SDP4 vs. Vallado’s reference set: 667 states, worst 0.12 mm · vs. Skyfield: 0.0003° elevation, 2.5 m range · How it is checked ↗
SHOWCASE 04 / OHFLOCK
The flock that fires nothing
Twenty-four small unarmed aircraft hold a relief corridor open at night against fighters, a SAM battery, AAA and strike jets. Hundreds of rounds are fired at them. Lasers blind trackers and paint decoy spots (sensors only, never people), thrown sound draws the guns, radar missiles lose them in the notch, and SatLink keeps them navigating to tens of metres by satellite Doppler while GNSS is jammed. The convoy gets through untouched.
./build/ohflock --html build/ohflock.html ./build/ohflock --no-satlink # what the satellites were worth ./build/ohflock --serve 1987 # gyde --url http://127.0.0.1:1987
Seek & Find: communications and quantum-interface simulation.
Explore a fictional scenario where simulated scouts restore a message path,
a mock inertial estimate informs a waypoint, a classical model illustrates
QKD basis sifting, and an inspection drone reaches a UV-marked USB prop. No
quantum device, secret key, cryptographic protection, radio, GPS, robot, or
external service is used; it does not train or command real machines.
Open the interactive demo
· Open the USD scene
· Read its scope and safety notes.
Try a local simulated aircraft: run
./build/gygax sim-autopilot, then follow the robotics guide to connect a service and issue commands to the virtual autopilot. The example is local simulation; real device control has separate safeguards and risks.05 / Operate
Configure the service for the environment you actually have.
The daemon runs with a selected inference engine, listens on a configured interface, and exposes health, readiness, metrics, and API endpoints. Deployment means choosing authentication, network placement, TLS termination, logging, supervision, and resource limits.
Start contained
Keep the default loopback bind while developing. The echo engine lets you test service behavior without an external model.
./build/gygax serve \
--engine echoPoint to an engine
Use a local chat-completions endpoint such as Ollama, llama.cpp or another supported backend. Model performance and availability remain properties of that engine.
./build/gygax serve \
--engine http://127.0.0.1:11434/v1 \
--model llama3.1Harden the boundary
Use a strong bearer token, TLS termination for traffic leaving the host, a supervisor, monitoring, and the documented systemd/container guidance.
06 / Boundaries
Be precise about what the controls do and don’t do.
Safe defaults reduce exposure. They do not remove the need for engineering judgment, threat modeling, or target-specific safety design.
Commands start disabled
Device command tools are only registered when the service is launched with --device-commands (or the corresponding environment setting). Treat enabling commands as a deliberate authority change.
Network exposure needs authentication
The service defaults to loopback and refuses a non-loopback bind without a token. For external traffic, use a TLS terminator and the token; the service itself speaks plain HTTP.
Simulation is not proof
A simulated success demonstrates behavior in a model of the world. It cannot certify a controller, validate a physical deployment, or guarantee that a real machine will respond identically.
A headset takes authority only when you let it
Under gygax serve --glyder, a pilot's sticks reach a real machine through the same --device-commands gate as the API; without it, a headset can watch but not drive. Sessions need the pairing code unless you choose --glyder-open, which is for a private, trusted network only.
Gygax is not a safety controller
It adds no safety layer to a vehicle. Keep the autopilot's failsafes, geofence, and a physical emergency stop. Complete the domain's safety case before operating equipment.
Enabling device commands does not add per-command human approval. Gygax has no built-in approval gate or universal hardware/simulation interlock. For detailed boundaries, see Public API and trust boundaries, Operations, Robotics safety model, and Security reporting.
07 / Verify
Trust the checks you can rerun.
Gygax includes unit and integration tests, a built-in doctor command, and scripts for deeper build, sanitizer, and service checks. Start with the targeted check that matches your change.
VALIDATION / FROM BUILD DIRECTORY
./build/gygax doctor
ctest --test-dir build --output-on-failure
./scripts/lint.sh
./scripts/dogfood.shProtocol interoperability has reference checks documented in Robotics. See Architecture for concurrency and runtime design. Test coverage is not a claim that every supported device or deployment has been validated.
08 / Field notes
Go deeper by subsystem.
The repository documentation is the source of truth for exact behavior, configuration, and limitations.
READMEProject overview and quick start
ArchitectureLayers, modules, threading, extension points
ServiceHTTP endpoints, engines, agents, tools
OperationsInstall, TLS, monitoring, hardening
RoboticsDevices, protocols, safety boundaries
NeuromorphicModels, units, determinism, bindings
LogisticsLedger, GUIDs, route planning
ExtensionsPlugins and tool processes
Public API & ABIVersioning, ownership, and trust boundaries
Acoustic studySimulation-only cancellation estimates and modulation limits
TransportsSerial, GPIO, modem, printer, G-code
ATARI protocolCompact tool-call wire format
WargamesAgent coordination and human directives
Seek & FindStandalone simulated communications and visual search demo
Quantum integrationSensor and QKD adapter interfaces, limitations, and security boundary
OHFLOCKAn unarmed flock, light, sound and SatLink
SatLinkSGP4/SDP4, Doppler, passes, rigctld, RTL-SDR
glyderVR: headset setup, pairing, drop-in, prescription optics
GydeOptional terminal runtime console
Open source · Clear BSD licence · C++26
Start with a question.
Make the answer observable.
Build the project, run the checks, inspect a showcase, and decide where the interfaces fit your system. Then test the assumptions that matter to your team.