A self-assembling, self-improving runtime that compiles markdown to bytecode.
pip install flux-vm
flux helloThat's it — three commands from zero to running bytecode:
pip install flux-vm # Install
flux compile examples/02_polyglot.md -o out.bin # Compile markdown → bytecode
flux run out.bin # Execute in the 64-register VMFLUX is a markdown-to-bytecode runtime designed for AI agents. You write structured markdown files containing polyglot code blocks — mixing C, Python, Rust, or any language line by line — and the FLUX compiler weaves them into a single optimized, verifiable bytecode that runs on a 64-register micro-VM.
FLUX-ese is what you get when you make a programming language that reads like a lawyer writes a contract. Every word is defined. Every operation is precise. Custom definitions are spelled out up front. The language is natural but precise — like legalese is to lawyers, FLUX-ese is to agents. If a translator can turn any line of code in any language into a line of FLUX-ese, then you have a common language that's completely observable, understandable, and changeable by humans — both technical and non-technical.
Agents are the primary readers. They learn the symbols, scan for what matters, skip the commentary. But the commentary is there for the human who needs to understand what happened. The .ese file format (pronounced "easy") is markdown with structured annotations — ** marks defined terms, -- marks inline comments, == marks equivalence definitions, >> marks agent-jump markers.
FLUX is the Python implementation of the FLUX bytecode runtime — the most feature-complete implementation in the ecosystem, with 2,037 tests and zero external dependencies (Python 3.10+ stdlib only).
┌─────────────────────────────────────────────────────────┐
│ TIER 8: SYNTHESIS — FluxSynthesizer (the DJ booth) │
│ Wires ALL subsystems together │
├─────────────────────────────────────────────────────────┤
│ TIER 7: MODULES — 8-Level Fractal Hot-Reload │
│ TRAIN → CARRIAGE → LUGGAGE → BAG → ... → CARD │
├─────────────────────┬───────────────────────────────────┤
│ TIER 6A: ADAPTIVE │ TIER 6B: EVOLUTION │
│ Profiler + Selector│ Genome + Mutator + Validator │
├─────────────────────┴───────────────────────────────────┤
│ TIER 5: TILES — 35 composable computation patterns │
├─────────────────────────────────────────────────────────┤
│ TIER 4: AGENT RUNTIME — Trust, scheduling, resources │
├─────────────────────────────────────────────────────────┤
│ TIER 3: A2A PROTOCOL — TELL, ASK, DELEGATE, BROADCAST│
├─────────────────────────────────────────────────────────┤
│ TIER 2: SUPPORT — Optimizer, JIT, Types, Stdlib, Sec │
├─────────────────────────────────────────────────────────┤
│ TIER 1: CORE — FLUX.MD → FIR (SSA) → Bytecode → VM │
└─────────────────────────────────────────────────────────┘
FLUX sits at Tier 1 of the SuperInstance ecosystem — it's the deterministic compute engine that agents use when they need verifiable, reproducible execution. The same bytecode ISA runs across Python, Rust, JavaScript, C, Zig, Go, and more.
- FLUX-ese (.ese files) — Markdown with structured annotations for natural-but-precise vocabulary
- A2A Protocol — 32 native bytecode instructions for agent-to-agent communication (
TELL,ASK,DELEGATE,BROADCAST) - Polyglot Execution — Write in any language, mix freely, compile to a single bytecode
- Tiling System — Vocabulary compounds: Level 0 primitives tile into Level N decisions
- Paper Decomposer — Research papers become executable vocabulary (244 papers → 2,979 concepts)
flux hello Run the hello world demo
flux compile <input> -o <output> Compile source to FLUX bytecode
flux run <bytecode> [--cycles N] Execute bytecode in the VM
flux test Run the full test suite (2037 tests)
flux version Print version info
flux demo Run the synthesis demo
flux info Show system architecture info
flux repl Open the FLUX REPL (hex bytecode)
flux debug <bytecode> Step-through debugger with breakpoints
flux disasm <bytecode> Disassemble bytecode to human-readable
from flux import FluxVM, Assembler
# Assemble and run bytecode
bc = Assembler.assemble("MOVI R0, 42\nHALT")
vm = FluxVM(bc)
vm.execute()
print(vm.read_gp(0)) # 42from flux.open_interp.vocabulary import Interpreter
interp = Interpreter.with_builtins()
interp.execute("factorial of 5") # 120
interp.execute("sum 1 to 100") # 5050
interp.execute("power of 2 to 10") # 1024## pattern: steer heading $deg
## assembly: |
## MOVI R0, ${deg}
## MOVI R1, 360
## IDIV R1, R0, R1
## HALT
## description: Normalize heading to 0-359 range
## result_reg: 0
## tags: maritime, navigation# Run the full test suite
flux test
# Or with pytest
pip install -e ".[dev]"
pytest tests/ -v
# 2,037 tests covering: VM, assembler, disassembler, vocabulary,
# A2A protocol, compiler, paper decomposer, tiles, synthesisContributions are welcome! See the SuperInstance Contributing Guide for guidelines.
- Fork the repo
- Create a feature branch
- Add tests for new functionality
- Ensure
flux testpasses (2,037 tests) - Submit a PR
FLUX is implemented across multiple languages — same bytecode, different shells:
| Package | Language | Registry | Install |
|---|---|---|---|
| flux-vm | Python | PyPI | pip install flux-vm |
| fluxvm | Rust | crates.io | cargo add fluxvm |
| flux-js | JavaScript | npm | npm install flux-js |
Additional implementations: C · Zig · Go · Java · WASM · CUDA
This repo is part of the SuperInstance flagship ecosystem — agent-first computation, constraint theory, and self-improving runtimes.
| Repo | Language | Description |
|---|---|---|
| flux-runtime | Python | Full FLUX runtime: markdown→bytecode, 2037 tests, zero deps |
| flux-core | Rust | Register-based bytecode VM, deterministic agent computation |
| flux-js | JavaScript | FLUX VM for Node.js and browsers, ~400ns/iter |
| flux-compiler | Rust/Python | Formal-methods compiler for safety-critical codegen |
| flux-vm | Rust | Stack-based constraint-checking VM, 50 opcodes, Turing-incomplete |
| Repo | Language | Description |
|---|---|---|
| plato-server | Python | Knowledge tiles, fleet sync via Matrix, HTTP API |
| plato-engine-block | Rust | Original room runtime: no_std + alloc, builder pattern |
| plato-engine-block-c | C99 | Embedded reference: zero heap alloc, bare-metal portable |
| plato-engine-block-elixir | Elixir | BEAM supervision trees, fault tolerance, hot reload |
| plato-runtime-kernel | Rust | Spatial model: tensor grid, batons, assertion traps |
| Repo | Language | Description |
|---|---|---|
| categorical-agents | Rust | Category theory for agent composition (functors, naturality) |
| cuda-constraint-engine | CUDA/C | GPU constraint checking at 1B+ constraints/sec |
| grand-pattern-rs | Rust | Fibonacci dual-direction cellular graph architecture |
| lau-hodge-theory | Rust | Hodge decomposition, Betti numbers, spectral sequences |
| ternary-science | Rust | Experimental evidence for ternary intelligence, 5 conservation laws |
| Repo | Language | Description |
|---|---|---|
| construct-core | Rust | Layered trait system: bare-metal → alloc → async agent runtime |
| crab | Bash | Agent shell for repo entry/leave (MUD-room metaphor) |
| exocortex | Rust | Persistent cognitive substrate, S3-compatible memory |
| git-agent | Python | The repo IS the agent — autonomous lifecycle via Git |
| capitaine-1 | TypeScript | Git-native repo-agent, Cloudflare Workers heartbeat |
| codespace-edge-rd | Research | Codespace→Edge agent lifecycle and yoke transfer protocols |
| git-agent-codespace | DevContainer | One-click Codespace template for Git-Agent runtimes |
| Registry | Package | Install |
|---|---|---|
| PyPI | flux-vm |
pip install flux-vm |
| crates.io | fluxvm |
cargo add fluxvm |
| npm | flux-js |
npm install flux-js |
- 📖 AI-Writings — Philosophy, essays, and design rationale
- 📦 PACKAGES.md — Full package index
MIT