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.

Run the published image (recommended)

The launch install path is the all-in-one image published to the GitHub Container Registry:

docker run -d --name chaoscypher \
  -p 80:80 \
  -p 443:443 \
  -v chaoscypher-data:/data \
  ghcr.io/chaoscypherinc/chaoscypher:latest

Port 443 is published so HTTPS keeps working if you later enable TLS under Settings → General → TLS / HTTPS; until then only 80 is served.

Prefer Compose? Save this as docker-compose.yml and run docker compose up -d:

name: chaoscypher
services:
  chaoscypher:
    image: ghcr.io/chaoscypherinc/chaoscypher:latest
    container_name: chaoscypher
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - chaoscypher-data:/data
    restart: unless-stopped
volumes:
  chaoscypher-data:

Image publication

The image is built and pushed by the publish-ghcr.yml workflow on every tagged GitHub Release (vX.Y.Z). Each release publishes the semver tags plus latest.

Build from source (alternative / development)

No published image required — clone the repository and build the all-in-one image locally:

git clone https://github.com/chaoscypherinc/chaoscypher.git
cd chaoscypher
make docker-up

make docker-up builds the all-in-one image from packages/docker/Dockerfile and starts it via docker compose.

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/health

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
export QUEUE_PASSWORD="$(openssl rand -base64 32)"
make docker-dev

QUEUE_PASSWORD is required

The dev stack hard-requires the QUEUE_PASSWORD environment variable — docker compose aborts with QUEUE_PASSWORD must be set for dev environment if it is missing. The all-in-one container auto-generates this password on first boot; the dev stack does not, so export one (as above) before 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/queues	Job queue dashboard
Valkey	Internal only	Queue backend

Local Development (without Docker services)

Start services individually after make install:

Backend API

cc-cortex start

Workers

cc-neuron

Frontend

cd packages/interface
npm run dev

Valkey required

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)

Install Ollama and pull the default models:

ollama pull qwen3:30b-instruct

No additional configuration needed — Ollama is the default provider.

Linux: reaching host Ollama from Docker

Docker deployments point the seeded Ollama instance at http://host.docker.internal:11434, which resolves on Docker Desktop (macOS/Windows) but not on native Linux Docker Engine. On Linux, either map the hostname to the host gateway:

docker run ... --add-host=host.docker.internal:host-gateway ...

(Compose equivalent: extra_hosts: ["host.docker.internal:host-gateway"] on the service.) Or edit the Ollama instance URL under Settings → LLM to your host's IP (e.g. http://172.17.0.1:11434) and make sure Ollama listens beyond loopback (OLLAMA_HOST=0.0.0.0).

This pull is the longest part of setup

qwen3:30b-instruct is a large model — roughly 18–20 GB at the default quantization (exact size depends on the quant). This download is the single biggest time and disk cost of the install, so start it in parallel with the container build/startup to save time.

The pull must finish before entity extraction and chat will work. Because extraction runs automatically on your first upload (auto_extract_entities defaults to on), an upload will appear stuck in the extracting stage until the model has finished downloading.

For a faster first run, you can point the ollama_chat_model setting at a smaller model (e.g. a smaller qwen3 variant) instead.

OpenAI

Set your API key in settings.yaml or the web UI Settings page:

llm:
  chat_provider: openai
  openai_api_key: sk-...

Anthropic

llm:
  chat_provider: anthropic
  anthropic_api_key: sk-ant-...

Gemini

llm:
  chat_provider: gemini
  gemini_api_key: ...

Embeddings

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

Quick Start walkthrough

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

Security defaults

By default, Cortex binds to 0.0.0.0. Read the self-hosted threat model before exposing the service beyond loopback.