System Architecture

How QuoxCORE is built, and how a question becomes a governed action with a record.

Maturity: Beta overall. This page describes how QuoxCORE is built, read from its code (QuoxCORE 1b8bf54d). Each part links to its own page, which states its own maturity.

At a glance
What it is	The map of QuoxCORE: which service does what, and how a request travels from your question to an action and a record of it.
Where it runs	Everything below runs as Docker containers on one server you own. Managed hosts are reached over SSH through QuoxBastion.
When to reach for it	You are deciding whether to deploy Quox, debugging an install, or extending it.
How to start	Install it with Install and deploy, then run `quox -p local health` to see each service below.

The services

QuoxCORE is eleven containers. Only the dashboard listens on your network.

Service	Job
Dashboard	The React web app, served by nginx over HTTPS
Collector	The core: chat, agents, tools, governance checks, fleet, AI routing and evidence
Auth	Accounts, organisations, roles and sessions
Memory	Typed memories (facts, preferences, decisions, entities, constraints) with full-text search
Qortex (`quox-brain`)	The knowledge layer: a knowledge graph and vault index
Orchestrator	Agent coordination
Tasks	Background jobs
QuoxFlow	The workflow engine (see below)
Files	File storage
Postgres	The database for QuoxFlow
Qdrant	Vector search, used for conversation recall and QuoxChat answers

Ports and profiles are listed in Install and deploy.

How a chat request flows

1. You ask, in the dashboard or with `quox chat`
      -> POST /chat/stream on the collector (a streamed reply)
2. A few fixed questions ("what is Quox", "help", "status") are
   answered directly, without calling a model
3. Everything else goes to CommanderQ, which may hand the job to a
   specialist agent with the delegate_to_agent tool
4. The agent calls the model you connected, and picks a tool
5. Every tool call passes one governance check first:
   denied, allowed, or held for a human approval
6. Allowed actions run: on the server, through an integration,
   or on a host over SSH through QuoxBastion
7. The action is recorded as an evidence envelope
8. The answer streams back to you

Models: you choose the provider

The collector is not tied to one AI vendor. A routing policy picks from the providers you have connected (Anthropic, OpenAI, Gemini, Perplexity, or a local server such as Ollama) and fails over to the next one when a call fails. Connect one with quox provider connect. See Introduction.

Agents

CommanderQ is the orchestrator. It hands work to specialist agents (for example NOVA for infrastructure, SENTINEL for security and CIPHER for networking) through a delegation tool. Each agent definition says which domains it covers and which tools it may use. See Agents.

Governance before every action

There is one check that every tool call passes through before it runs. Policy can deny the call, allow it, or require a human approval, and the check fails closed. Destructive tools are also wrapped in an approval gate, which is on by default. Above that sits the instance safety level, GREEN to RED, which can hold or halt autonomous work. See Safety and Policies.

Reaching your hosts

Commands reach managed hosts over SSH through QuoxBastion. QuoxAgent runs on each host to report events and sessions. Both are optional: without QuoxBastion, host tools answer "Bastion not configured" and agents work on the server and its integrations only.

Evidence

Governed actions are written as AEE envelopes, and each one is witnessed into WARD, a hash chain where every entry carries the hash of the one before. Editing an old entry breaks every hash after it. See Evidence spine, AEE and WARD.

Workflows

QuoxFlow runs workflows built from typed nodes, records an evidence trail for each run, and applies the same allow, deny or require-approval policy, with human approval steps. It can import n8n workflow JSON, but it does not need n8n to run. See Workflows.

Voice

The collector has two voice routes: /voice/transcribe (speech to text with OpenAI Whisper) and /voice/speak (text to speech with ElevenLabs). Both need that provider's key.

Technology

Part	Built with
Dashboard	React 19, Vite 7
Collector and services	Node.js
Workflow engine	QuoxFlow, TypeScript
Data	SQLite per service, Postgres for QuoxFlow, Qdrant for vectors
Host access	QuoxBastion (Go) and QuoxAgent (Go)
Deployment	Docker Compose

Limits

Delegation limits are logged, not yet enforced. Each agent has a list of agents it may delegate to; a call outside that list is recorded but not blocked today.
Voice needs third-party keys. Whisper and ElevenLabs are external services; nothing is transcribed without your key.
This page is read from code. How far each part has been driven live is stated on its own page.

Install and deploy: run this stack yourself.
Introduction: the five ideas, in plain words.
Safety: approvals, safety levels and the emergency stop.
Evidence spine: how actions become verifiable records.
QuoxCLI: every quox command.

Last verified 2026-10-29 against QuoxCORE 1b8bf54d (code).