Free Store
Get started

Quickstart

Get Quox running in under 10 minutes.

Get QuoxCORE, the self-hosted control plane for AI agents, running and put agents to work on your infrastructure.

PrerequisitesLinux or macOS, Docker with Compose v2, Git
Minimum Resources4GB RAM, 10GB disk

Step 1: Install

The fastest path is the one-line installer. It clones QuoxCORE and its required sibling repos over HTTPS, prepares your environment, and starts the stack:

bash
curl -fsSL https://get.quox.ai | sh

Prefer to see each step yourself? Clone the repos directly (HTTPS, no SSH key needed) and run the preflight check:

bash
git clone https://github.com/quoxai/quox.git && \
  git clone https://github.com/quoxai/quoxflow.git && \
  git clone https://github.com/quoxai/quoxmcp.git && cd quox

# Run the preflight check
./scripts/preflight.sh

The preflight script verifies your system is ready:

QuoxCORE Preflight Check
========================================

Operating System:
  ✓ Ubuntu 24.04

Docker:
  ✓ Docker 27.5.1 (running)
  ✓ Docker Compose v2.32.4

Node.js:
  ✓ Node.js v22.13.1

Memory:
  ✓ Total: 16GB (minimum: 4GB)

Disk Space:
  ✓ Available: 87GB (minimum: 10GB)

Required Ports:
  ✓ Port 3000 available
  ✓ Port 3101 available
  ✓ Port 6333 available

========================================
All critical checks passed!

If any checks fail, resolve them before continuing.

Step 2: Generate Secrets

If you used the one-line installer, this already happened; skip to Step 4. If you cloned manually:

bash
./scripts/generate-secrets.sh

This creates your .env file from .env.example and generates cryptographically secure values for:

  • JWT_SECRET - Authentication token signing
  • ENCRYPTION_KEY - Data encryption
  • MASTER_ENCRYPTION_KEY - Master key for secrets management

Existing values are preserved if you run the script again.

Add API Keys (Optional)

Edit .env to add your AI provider keys:

bash
# Required for AI conversations
ANTHROPIC_API_KEY=sk-ant-...

# Required for semantic memory search (embeddings)
OPENAI_API_KEY=sk-...

# Optional - voice output (text-to-speech)
ELEVENLABS_API_KEY=...

Without API keys, you can still explore the dashboard in demo mode by setting VITE_DEMO_MODE=true.

Step 3: Start Services

bash
docker compose up -d

QuoxCORE runs 12 services:

ServicePortPurpose
Dashboard3000React frontend (nginx)
Auth3101Authentication, RBAC, tenant management
Files3102File storage service
Collector9848Chat streaming (SSE), fleet management, AI routing
Memory3103Persistent memory service (episodic, semantic, entity)
Tasks—Background task runner
Orchestrator—Agent coordination service
QuoxFlow—Workflow execution engine
Qdrant6333Vector database for semantic search
PostgreSQL5432Relational database
n8n5678Visual workflow editor (optional, via --profile with-n8n)
Screencap—Screenshot capture service

Verify all services are running:

bash
docker compose ps

Expected output shows all services with running (healthy) status.

Services have health checks and dependency ordering. The dashboard waits for auth and collector to be healthy before starting.

Step 4: Setup Wizard

Open your browser to http://localhost:3000

The setup wizard walks you through:

  1. Create your account - First user becomes the system administrator
  2. Create your organisation - Set up your primary org
  3. Configure AI providers - Enter API keys if you haven't already
  4. Choose your agents - Select which AI agents to enable

After completing the wizard, you'll land on the main dashboard.

Step 5: First Conversation

Click into the Command view to start chatting with Quox.

Quox uses a multi-agent system. The orchestrator (CommanderQ) automatically delegates queries across 49 specialist agents, including:

  • NOVA - Infrastructure and CI/CD
  • SENTINEL - Security operations
  • CIPHER - Network troubleshooting
  • ATLAS - Virtualization (Proxmox)
  • METRICS - Monitoring and observability

Try asking:

What can you help me with?

Or if you have infrastructure connected:

Show me the fleet status

Step 6: Connect QuoxAgent (Optional)

QuoxAgent is a lightweight daemon that runs on hosts you want Quox to manage. It provides secure remote execution without exposing SSH credentials.

On each host you want to manage:

bash
# Install QuoxAgent
curl -sSL http://YOUR_QUOX_IP:9848/install | sudo bash -s -- \
  --host-id $(hostname) \
  --collector http://YOUR_QUOX_IP:9848

Replace YOUR_QUOX_IP with the IP address of your QuoxCORE server.

Verify Connection

bash
# On the managed host
systemctl status quoxagent

# Check the API
curl -s http://localhost:9847/api/v1/status

Connected hosts appear in the NOC (Network Operations Center) view on the dashboard.

Common Issues

Services Won't Start

bash
# Check logs for a specific service
docker compose logs auth
docker compose logs collector

# Check all logs
docker compose logs -f

Port Conflicts

bash
# Find what's using a port
lsof -i :3000   # Dashboard
lsof -i :3101   # Auth
lsof -i :6333   # Qdrant
lsof -i :9848   # Collector

Ports are configurable in .env:

bash
DASHBOARD_PORT=3000
AUTH_PORT=3101
FILES_PORT=3102
COLLECTOR_PORT=9848
QDRANT_PORT=6333

CORS Errors

If the dashboard can't reach backend services, check CORS_ORIGINS in .env:

bash
# For local development
CORS_ORIGINS=http://localhost:3000

# For remote access (replace with your IP or domain)
CORS_ORIGINS=http://192.168.1.100:3000

Restart services after changing .env:

bash
docker compose down && docker compose up -d

Setup Wizard Not Loading

  1. Ensure all services show healthy in docker compose ps
  2. Check auth service logs: docker compose logs auth
  3. Verify CORS_ORIGINS matches the URL you're accessing

Useful Commands

bash
# Stop all services
docker compose down

# Rebuild after code changes
docker compose build && docker compose up -d

# View real-time logs
docker compose logs -f

# Restart a single service
docker compose restart collector

# Check disk usage
docker system df

Next Steps