Quick Start

This walkthrough takes about 5 minutes. You'll upload a document, explore the extracted knowledge graph, and ask a question using AI chat.

1. Start the services

make docker-up

Wait for the container to become healthy, then open http://localhost. After signing in (first run prompts you to set a username and password), you land on the Dashboard — a live overview of your graph with entity, relationship, source, and quality counts plus a recent-activity feed.

First startup

The first startup may take a few minutes while Docker builds the image. Subsequent starts are faster.

Startup page

When the container first starts, your browser shows a startup page with live health indicators for each service (Nginx, Cortex, Valkey, Neuron). The page auto-redirects to the application once all services are healthy — typically 30-60 seconds on first start.

Development mode

If you're using the multi-container dev setup (make docker-dev), the UI is at http://localhost:3000 and the API at http://localhost:8080 instead.

API port in curl examples

The curl examples below use localhost:8080, which is the direct Cortex API port used in dev mode. If you are running the all-in-one deployment (make docker-up), replace 8080 with port 80 — i.e., use http://localhost/api/v1/... instead.

2. Upload a document

Web UI

1. Navigate to Sources in the sidebar
2. Click Upload and select a PDF, Word document, or text file
3. The file enters the processing pipeline automatically

CLI

chaoscypher source add document.pdf

The CLI runs the full pipeline (upload → index → extract → commit) and shows a progress bar for each stage.

Python

from chaoscypher_core import ChaosCypher

result = ChaosCypher.add_document_sync("document.pdf")
print(f"Created {len(result.nodes)} nodes, {len(result.edges)} edges")

API

curl -X POST http://localhost:8080/api/v1/sources \
  -F "file=@document.pdf"

Response 202 Accepted:

{
  "id": "src_abc123",
  "filename": "document.pdf",
  "status": "pending",
  "file_type": "pdf",
  "file_size": 204800,
  "created_at": "2026-03-09T14:30:00"
}

The source enters the processing pipeline automatically. Poll its status with GET /api/v1/sources/{id} and watch the status field progress through the pipeline stages.

The processing pipeline has two stages:

Stage	What happens	Time
Indexing	Chunking + embedding for RAG search	~30s per 100 pages
Entity Extraction	AI extracts entities and relationships	~5min per 100 pages

Status indicators

Watch the status badge on your source file: indexing → indexed → extracting → extracted → committing → committed

3. Search your documents

Once a source reaches indexed status, you can search it:

Web UI

1. Navigate to Search in the sidebar
2. Type a query — results come from both keyword and semantic (vector) search
3. Click a result to see the source chunk with highlighted matches

CLI

chaoscypher source search "your query here"

Supports --mode keyword, --mode semantic, or --mode hybrid (default).

Python

from chaoscypher_core import ChaosCypher

results = ChaosCypher.search_sync("your query here")
for r in results:
    print(f"{r.score:.3f}  {r.label}")

API

curl "http://localhost:8080/api/v1/search?q=your+query+here&search_type=hybrid"

Response 200 OK:

{
  "data": [
    {
      "result_type": "chunk",
      "score": 0.89,
      "chunk": {
        "content": "The key findings indicate...",
        "filename": "document.pdf",
        "page_number": 3,
        "section": "Introduction"
      },
      "node": null
    }
  ],
  "type": "hybrid"
}

Available search_type values: keyword, semantic, hybrid. Add &limit=10 to control result count.

4. Explore the knowledge graph

Once extraction is committed, entities and relationships appear in the graph:

Web UI

1. Navigate to Graph in the sidebar
2. The canvas shows extracted nodes (entities) and edges (relationships)
3. Click a node to see its properties, connected entities, and source evidence
4. Use the search bar to find specific entities
5. Try different layout options from the toolbar

CLI

# List all nodes
chaoscypher graph node list

# View a specific node with its connections
chaoscypher graph node get NODE_ID --include-links

# Search for entities
chaoscypher source search "entity name"

Python

from chaoscypher_core import Engine

with Engine("./data/databases/default") as engine:
    result = engine.list_nodes()
    for node in result.data:
        print(f"{node.label} ({node.template_id})")

    stats = engine.get_stats()
    print(f"Graph: {stats.nodes} nodes, {stats.edges} edges")

API

# List all nodes
curl "http://localhost:8080/api/v1/nodes?page=1&page_size=20&include_stats=true"

# Get a specific node with its connections
curl http://localhost:8080/api/v1/nodes/{node_id}/connections

Response 200 OK (list nodes):

{
  "data": [
    {
      "id": "node-a1b2c3d4",
      "template_id": "person",
      "label": "Albert Einstein",
      "properties": {"field": "Physics"},
      "edge_count": 12,
      "citation_count": 3
    }
  ],
  "pagination": {"page": 1, "page_size": 20, "total": 87}
}

Use GET /api/v1/counts for a quick summary of nodes, edges, templates, and sources.

5. Chat with your documents

Web UI

1. Navigate to Chat in the sidebar
2. Start a new conversation
3. Ask a question about your uploaded document

The AI uses RAG to search your indexed content and provides answers with citations linking back to specific source chunks.

!!! tip "Scoped chat" Open the chat dropdown on a specific source to start a conversation scoped to that document only. The AI will only use content from that source.

CLI

# Quick one-shot question
chaoscypher chat "What are the key findings?"

# Interactive chat session
chaoscypher chat

The CLI displays tool calls and citations inline as the response streams.

Python

from chaoscypher_core import Engine

async with Engine("./data/databases/default") as engine:
    response = await engine.chat("What are the key findings?")
    print(response.content)

API

# 1. Create a conversation
curl -X POST http://localhost:8080/api/v1/chats \
  -H "Content-Type: application/json" \
  -d '{"title": "Quick Start Chat"}'

# 2. Stream an AI response (SSE)
curl -N -X POST http://localhost:8080/api/v1/chats/{chat_id}/stream \
  -H "Content-Type: application/json" \
  -d '{"role": "user", "content": "What are the key findings?"}'

The stream endpoint returns Server-Sent Events with content, tool_calls, tool_result, and done events. The done event includes the final response with citations:

data: {"type": "content", "delta": "Based on", "accumulated": "Based on"}
data: {"type": "done", "content": "Based on the analysis...", "chunk_citations": [...]}

6. Manage databases

Chaos Cypher supports multiple isolated databases:

Web UI

1. Go to Settings → Databases
2. Create a new database for a different project or topic
3. Switch between databases — each has its own sources, graph, and chat history

CLI

# List all databases
chaoscypher db list

# Create a new database
chaoscypher db create research-project

# Switch to it
chaoscypher db switch research-project

Python

from chaoscypher_core import Engine

# Each Engine instance targets a specific database
with Engine("./data/databases/research-project") as engine:
    stats = engine.get_stats()
    print(f"Nodes: {stats.nodes}, Edges: {stats.edges}")

API

# List all databases
curl http://localhost:8080/api/v1/databases

# Create a new database
curl -X POST http://localhost:8080/api/v1/databases \
  -H "Content-Type: application/json" \
  -d '{"name": "research-project"}'

# Switch to it
curl -X PATCH http://localhost:8080/api/v1/databases/current \
  -H "Content-Type: application/json" \
  -d '{"name": "research-project"}'

Response 200 OK (list databases):

{
  "databases": [
    {"name": "default", "size": 524288, "last_modified": "2026-03-09T14:22:10+00:00"},
    {"name": "research-project", "size": 262144, "last_modified": "2026-03-09T15:00:00+00:00"}
  ]
}

Security defaults

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

What's next?

• Sources guide — Learn about batch uploads, URL imports, and processing options
• Knowledge Graph guide — Manual node creation, templates, and graph exploration
• Chat guide — Scoped conversations, citations, and LLM configuration
• Configuration — Customize LLM providers, chunking, search, and more