Chaossynergy
The OS is the agent interface.
immutable · agent-native · atomiclatest
Chapter 26 — Local inference and the agent toolchain. Two new ADRs extend Chaossynergy with offline inference and on-demand coding agents. Read on onlyascii.dev
The journey starts with Chapter 25 — the philosophy, the architecture decisions, and the alpha prototype.
philosophy
Chaossynergy is an operating system shaped around one purpose: being the substrate that an AI agent lives in and operates through. Not Linux with an assistant installed. Not a CLI tool that talks to an LLM. An entire OS designed for human-AI collaboration.
The name is a contradiction made real. Chaos — the unpredictable, emergent behaviour of multiple agents, containers, and runtimes working in parallel. Synergy — the whole working together as one system, directed by a single conductor.
The substrate is sacred and dumb
Immutable, atomic, minimal. An appliance that exists only to boot the agent. If the agent breaks, delete the container. The host is untouched.
The agent is disposable
Hermes runs in a distrobox container with its own state. Break it? distrobox rm agent. Fresh runtime in 30 seconds.
Safety by construction
bootc provides atomic OS updates at the kernel level. Distrobox isolates the agent at the user level. One layer can fail and the other still holds.
architecture
Six integrated layers, one unified system. Everything the agent needs lives in a disposable distrobox container. The host OS stays minimal.
Host OS (minimal)
Bluefin LTS (CentOS Stream 10) — just herdr, systemd services, GDM auto-login. No browsers. No Node.js. No Hermes. An appliance.
herdr Multiplexer
Fullscreen Ptyxis terminal on boot. Agent-aware sidebar. Every shell auto-enters the distrobox via the chaossynergy-shell wrapper.
Agent Container
Fedora distrobox with Chromium, Node.js, Hermes, pass. Shared home directory so the agent sees your projects and configs.
Recovery Shell
Shift-at-boot emergency root shell. If the agent or multiplexer fails, you always have a way back in.
Inference Runtime
Dedicated distrobox for local LLM inference. Mutually exclusive engines: llama.cpp (port 8080) or vLLM (port 8000). Auto-downloads GGUFs via HuggingFace. RTX 5090 32GB VRAM.
Agent Toolchain
Isolated distroboxes for OpenCode, Pi (pi.dev), and Claude Code. Each is a self-contained coding agent. Lazy-installed on first use via ujust.
Hermes ◄──► npx @browsermcp/mcp ──WebSocket──► Chromium Extension
│ │
└──► pass show hermes/openrouter browserpass fills login forms
~/.password-store/ ◄──── browserpass-native ◄──── browserpass extagents & inference
Chaossynergy ships with ujust commands for setting up coding agents and local LLM inference. All run in isolated distrobox containers. No cloud dependency.
Coding agents
$ ujust setup-opencode # OpenCode distrobox $ ujust setup-pi # Pi (pi.dev) distrobox $ ujust setup-claude # Claude Code distrobox $ ujust list-agents # List installed agents $ ujust remove-agent # Remove an agent container
Local inference
$ ujust setup-inference-llama # llama.cpp (port 8080) $ ujust setup-inference-vllm # vLLM (port 8000) $ ujust inference-model # Switch quant (Q4_K_M / Q8_0) $ ujust inference-status # Check inference status $ ujust inference-logs # Tail inference logs $ ujust inference-restart # Restart inference engine $ ujust inference-stop # Stop inference engine
Both inference engines are mutually exclusive due to VRAM contention
(RTX 5090 32GB). Running ujust setup-inference-vllm
stops llama.cpp first, and vice versa. Default model:
bottlecapai/ThinkingCap-Qwen3.6-27B-GGUF:Q4_K_M
(or :Q8_0).
quick start
$ just build $ just build-qcow2 $ just run-vm-qcow2
Or deploy from the registry:
$ sudo bootc switch ghcr.io/dark5un/chaossynergy:latest $ sudo systemctl reboot
On first boot, press n in herdr to create a workspace, then type distrobox enter agent.
architecture decisions
- ADR-001 — Base image, build system, provisioning, UI
- ADR-002 — herdr terminal multiplexer
- ADR-003 — Shared home directory
- ADR-004 — Multi-agent architecture
- ADR-005 — Minimal host, container-first
- ADR-006 — Browser MCP + browserpass
- ADR-007 — pass secrets management
- ADR-008 — GNOME autostart with fullscreen terminal
- ADR-009 — Local voice dictation (proposed)
- ADR-010 — Visual context for agent-human pairing (proposed)
- ADR-011 — Local inference runtime
- ADR-012 — Agent toolchain
roadmap
Chaossynergy is in alpha. The foundation works. It boots, builds, and connects. Here is where we are heading:
Alpha prototype
Bootable image boots into GNOME, launches herdr, connects to agent container. CI builds pass. Images published to GHCR.
Agent toolchain
OpenCode, Pi, and Claude Code in isolated distrobox containers. Each is a self-contained coding agent, lazy-installed on demand via ujust.
Local inference
Dedicated inference distrobox with llama.cpp (port 8080) or vLLM (port 8000). Auto-downloads GGUFs via HuggingFace. Mutually exclusive engines managed by ujust.
Bootable disk images
qcow2 and ISO builds via bootc-image-builder. Install on bare metal or VM without needing an existing Bluefin install.
Browser MCP + pass
Wire Browser MCP Chrome extension to Hermes. Integrate browserpass for shared secrets between the agent and the browser.
Multi-agent orchestrator
Multi-agent coordination layer. Hermes delegates to OpenCode, Pi, or Claude Code via socket API. Agents spawning agents.
Voice dictation
Whisper.cpp push-to-talk. Press a key, speak, text appears in the active application. Fully local, no cloud.
Presence-aware pairing
Opt-in camera sensing. Tiered: presence safety gate, gaze attention awareness, expression interaction dynamics. Fully local, no recording, no cloud.
links
see it in action
built with
Chaossynergy stands on the shoulders of giants. Our thanks to: