Quickstart

FreeChaOS ships as a single native binary, chaos. It needs an LLM provider API key (or a local model) and nothing else.

Prerequisites

To run FreeChaOS:

Linux 6.10+, macOS 15+, or FreeBSD 15+ (Windows is not supported)
~80 MB RAM (MCP mode) or ~128 MB (TUI mode) - MCP servers not included
At least one model provider API key, or a local model (e.g. Ollama)

To build from source:

Rust (the repo pins its toolchain via rust-toolchain.toml)
just
Git 2.53+ (optional, recommended)

Steps

Install the prebuilt binary.
Terminal window
```
curl -fsSL https://raw.githubusercontent.com/seuros/chaos/master/install.sh | sh
```
This downloads the latest release for your OS/CPU into ~/.local/bin. Override the destination with CHAOS_INSTALL_DIR=/path/to/bin.

Or build from source:
Terminal window
```
git clone https://github.com/seuros/chaos.git
cd chaos
just install
```
just install builds with -C target-cpu=native and drops the binary into ~/.cargo/bin/chaos. For a one-shot debug run without installing, use just chaos; for a local release run, just bigbang.
Export a provider key.
Terminal window
```
export ANTHROPIC_API_KEY=sk-ant-...
# or
export OPENAI_API_KEY=sk-...
```
OpenAI, Anthropic, xAI, and Z.ai are built in. Anything else - DeepSeek, Groq, Ollama, self-hosted gateways - is a config entry in ~/.chaos/config.toml. See Providers.
Start a session.
Terminal window
```
chaos --provider anthropic --model haiku
```
The TUI opens with a Doom-style HUD statusline: remaining context is your HP, the active model is your WPN. Press ctrl+o for the log viewer overlay.
Or run non-interactively.
Terminal window
```
chaos exec "summarize the failing tests"
```
chaos exec runs one prompt and exits - useful in scripts and CI. Add -d / --debug on any subcommand to write debug logs to ~/.chaos/debug.log.
Wire up drivers.

MCP servers give FreeChaOS its tools:
Terminal window
```
chaos mcp add my-server -- bunx my-mcp-server
chaos mcp list
```
Project-local servers go in .mcp.json, shared with Claude Code and other MCP-aware harnesses. See Drivers (MCP).

Next steps

Architecture: kernel, modules, and drivers - how the OS is put together.
Providers: wire formats, selection rules, and config for every provider.
Drivers (MCP): connect tools and services, or expose FreeChaOS itself over MCP.
Halluacinate: teach the agent new tools in Lua without recompiling.
HTTP Trigger Server: run FreeChaOS as a webhook target with chaos serve.