flux-registry 0.1.0

FLUX Registry — Pre-compiled agent policies, installable and runnable

FLUX Registry

npm for agent policies. Pre-compiled FLUX bytecode, installable and runnable.

Pre-compiled agent policies, installable and runnable. The registry is a static JSON index on GitHub — no server required. The CLI downloads from raw.githubusercontent.com and caches policies locally in ~/.flux/policies/.

Install

pip install flux-registry

Quick Start

# Browse available policies
flux list --remote

# Install a policy
flux install deadband-controller

# Run it
flux run deadband-controller --input temperature=72
# Output: action=idle

flux run deadband-controller --input temperature=80
# Output: action=cool

flux run deadband-controller --input temperature=60
# Output: action=heat

# Get details
flux info deadband-controller

Commands

Command	Description
flux install <policy>	Install a policy from the remote registry
flux list [--remote]	List installed (or remote) policies
flux info <policy>	Show detailed metadata, inputs, outputs
flux run <policy> --input K=V	Execute a policy with given inputs
flux remove <policy>	Remove an installed policy
flux update-index	Refresh the local registry cache

Available Policies

Policy	Description	Inputs	Outputs
deadband-controller	Thermostat with hysteresis — AC at 75°, heat at 65°	temperature (°F)	action: idle/cool/heat
budget-tracker	Conservation budget enforcement — track resource depletion	cost, budget	remaining, status: ok/exceeded
rate-limiter	Token bucket rate limiting — check and consume tokens	tokens, cost	remaining, allowed: denied/allowed
security-scanner	Basic vulnerability detection — threshold-based policy check	value, threshold	verdict: safe/violation, severity

Policy Format

Each policy is a JSON file containing:

{
  "name": "deadband-controller",
  "version": "0.1.0",
  "description": "Thermostat deadband controller",
  "author": "SuperInstance",
  "bytecode": "<base64-encoded FLX0 binary>",
  "source": "deadband-controller.flx",
  "bytecode_hash": "sha256...",
  "bytecode_size": 32,
  "inputs": [{"name": "temperature", "type": "float", "register": "R0"}],
  "outputs": [{"name": "action", "type": "int", "register": "R1",
               "values": {"0": "idle", "1": "cool", "2": "heat"}}],
  "conservation": {"max_steps": 100, "memory_budget": 256},
  "conformance": "verified on flux-vm 0.1.0, fluxvm 0.1.0, flux-js 0.1.0",
  "tags": ["iot", "thermostat", "hvac"],
  "license": "MIT"
}

Architecture

┌──────────────────────────────────────────────────────┐
│                   FLUX Registry                       │
│                                                       │
│  GitHub (static JSON)          Local (~/.flux/)       │
│  ┌─────────────────┐          ┌──────────────────┐   │
│  │ registry/       │  install │ policies/        │   │
│  │   index.json    │ ───────▶ │   deadband.json  │   │
│  │   deadband.json │          │   budget.json    │   │
│  │   budget.json   │          └────────┬─────────┘   │
│  │   rate-limiter  │                   │              │
│  │   security.json │          ┌────────▼─────────┐   │
│  └─────────────────┘          │   flux CLI       │   │
│                               │   ┌────────────┐ │   │
│                               │   │ Mini FLUX  │ │   │
│                               │   │ VM (built  │ │   │
│                               │   │  in)       │ │   │
│                               │   └────────────┘ │   │
│                               └──────────────────┘   │
└──────────────────────────────────────────────────────┘

The mini FLUX VM is built into the CLI for zero-dependency local execution. For production use, policies can be run on any FLUX implementation:

Runtime	Language	Install
flux-vm	Python	pip install flux-vm
fluxvm	Rust	cargo add fluxvm
flux-js	JavaScript	npm install flux-js

All run the same bytecode — same policy, different shells.

Conservation Guarantees

Every policy declares conservation limits:

"conservation": {
  "max_steps": 100,
  "memory_budget": 256
}

The VM enforces these at runtime — a policy cannot exceed its step count or memory allocation. This makes FLUX policies safe to run as untrusted code.

Adding Policies

1. Write a policy in .flx source
2. Compile with flux-compiler
3. Create a JSON manifest with bytecode + metadata
4. Submit a PR to add it to registry/

License

MIT — Same bytecode, different shells. 🦀

Related

• flux-vm — Stack-based constraint VM (50 opcodes)
• flux-compiler — Formal-methods compiler
• flux-js — JavaScript VM
• PACKAGES.md — Full package index