Installation
Prerequisites
| Requirement | Version | Purpose |
|---|---|---|
| Docker | Latest | Container orchestration |
| Make | Any | Build commands (optional) |
| uv | 0.11+ | Python dependency management (contributors only — end users only need Docker) |
You also need an LLM provider. Ollama is recommended for fully local operation.
Install uv via the official installer — curl -LsSf https://astral.sh/uv/install.sh | sh on macOS/Linux, or the equivalent PowerShell command on Windows.
Docker All-in-One (Recommended)
The fastest way to get Chaos Cypher running. A single container with all services bundled.
Pre-built Docker images at ghcr.io/chaoscypherinc/chaoscypher will be available at general availability. Until then, build locally from the repository:
git clone https://github.com/chaoscypherinc/chaoscypher.git
cd chaoscypher
make docker-up
This starts everything at http://localhost:
| Port | Service |
|---|---|
| 80 | Web UI + REST API (via Nginx) |
| 443 | HTTPS (optional, requires TLS certs) |
Startup
While services initialize, the browser shows a startup page with live component health indicators and a real-time log viewer. Once all services are ready, the page automatically redirects to the application.
If you encounter an error, custom error pages provide contextual messages and a link to report issues on GitHub with pre-filled diagnostic information.
Verify
Open http://localhost in your browser. You should see the startup page briefly, then the Chaos Cypher interface.
Check the API is responding:
curl http://localhost/api/v1/settings
Multi-Container (Development)
For contributors working from an approved development checkout who need hot-reload and per-service logs. Requires Python 3.14+ and Node.js 22+.
cd chaoscypher
make install
make docker-dev
make install handles:
- Installing Python packages for all backend packages (core, cortex, neuron, cli)
- Installing Node.js dependencies for the interface
- Setting up pre-commit hooks
- Building the Docker test image
This starts separate containers:
| Service | URL | Description |
|---|---|---|
| Interface | http://localhost:3000 | Web UI (Vite HMR) |
| Cortex API | http://localhost:8080/api/v1 | REST API (auto-restart) |
| Queue Monitor | http://localhost:3000/queue-monitor | Job queue dashboard |
| Valkey | Internal only | Queue backend |
Local Development (without Docker services)
Start services individually after make install:
- Backend API
- Workers
- Frontend
cc-cortex start
cc-neuron
cd packages/interface
npm run dev
The worker (Neuron) requires Valkey. Start it separately:
docker run -d -p 6379:6379 valkey/valkey:8-alpine
CLI Only
If you only need the command-line interface:
pip install chaoscypher-cli
Verify:
chaoscypher --help
LLM Provider Setup
Chaos Cypher requires an LLM provider for chat and entity extraction. Embeddings are generated locally on the CPU and do not require an LLM provider.
- Ollama (Local)
- OpenAI
- Anthropic
- Gemini
Install Ollama and pull the default models:
ollama pull qwen3:30b-instruct
No additional configuration needed — Ollama is the default provider.
Set your API key in settings.yaml or the web UI Settings page:
llm:
chat_provider: openai
openai_api_key: sk-...
llm:
chat_provider: anthropic
anthropic_api_key: sk-ant-...
llm:
chat_provider: gemini
gemini_api_key: ...
Vector embeddings are generated locally on the CPU using sentence-transformers. No LLM provider configuration is needed for embeddings — they work automatically and offline.
Next Steps
Troubleshooting
Port already in use
If port 80 is taken, change the host port in your environment:
HOST_PORT_HTTP=8080 make docker-up
Volume permissions
The container runs as appuser (uid 1000). If you see permission errors on mounted volumes, ensure the host directory is writable by uid 1000.
Switching between deployment modes
When switching between all-in-one and multi-container modes, stop all services first to avoid port conflicts:
make docker-down
By default, Cortex binds to 0.0.0.0. Read the self-hosted threat model before exposing the service beyond loopback.