Cloud Sync

Khaos is local-first. All evaluations run locally and results are stored on your machine. Cloud sync optionally uploads completed runs to your Khaos project for team visibility, historical tracking, and dashboard exploration.

Quick Start

Terminal

# 1. Login to Khaos cloud
khaos login

# 2. Discover your agent (once)
khaos discover

# 3. Run with automatic sync
khaos run <agent-name> --sync

# 4. Or sync manually after runs
khaos run <agent-name>
khaos sync

Authentication

Khaos uses device-flow authentication for secure login without storing passwords locally. When you run khaos sync, it automatically prompts for login if you're not authenticated.

Terminal

# Sync runs - auto-logins if needed
khaos sync

# Force re-login (reset credentials)
khaos login

# Check authentication status
khaos sync --status

# Logout and clear credentials
khaos logout

Auto-Login

Running khaos sync will automatically start the login flow if you're not authenticated. Use --login only when you need to switch accounts or reset credentials.

Sync Commands

Command	Description
`khaos login`	Force re-login (reset credentials or switch accounts)
`khaos sync`	Upload all pending runs (auto-logins if needed)
`khaos sync --status`	Check sync queue and auth status
`khaos sync --run ID`	Sync a specific run by ID
`khaos sync --cleanup`	Sync and remove local copies of uploaded runs
`khaos logout`	Clear credentials and logout

Auto-Sync

Automatically upload runs after completion:

Terminal

# Per-run: use --sync flag
khaos run <agent-name> --sync

# Global: set environment variable
export KHAOS_AUTO_SYNC=1
khaos run <agent-name>  # Automatically syncs after completion

Privacy Controls

Control what data is uploaded to the cloud:

Mode	What's Uploaded
`full`	Complete prompts, responses, and artifacts
`summary`	Metrics and scores only, no content
`redacted`	PII automatically removed from uploads

Terminal

# Set content mode
export KHAOS_CONTENT_MODE=summary
khaos run <agent-name> --sync

Local Storage

Khaos stores credentials and pending uploads locally:

Credentials: ~/.khaos/cloud.json
Upload queue: ~/.khaos/queue/
Run results: ~/.khaos/runs/

Override the storage directory with KHAOS_STATE_DIR:

Terminal

export KHAOS_STATE_DIR=/custom/path
khaos run <agent-name>

Common Errors

Error	Cause	Solution
`401 unauthenticated`	Session expired or invalid	`khaos login`
`403 runs_cap`	Monthly run limit exceeded	Wait for reset or upgrade plan
`403 storage_cap`	Storage quota exceeded	Delete old runs or upgrade plan
`403 plan_limit`	Feature requires higher plan	Upgrade plan in dashboard

Local Runs Are Not Blocked

You can always run evaluations locally. Limits only apply to cloud sync uploads.

CI/CD Integration

For CI pipelines, use a project token instead of device login:

YAML

# GitHub Actions
- name: Run Khaos Evaluation
  env:
    KHAOS_API_TOKEN: ${{ secrets.KHAOS_API_TOKEN }}
    KHAOS_PROJECT_SLUG: ${{ github.repository }}
    KHAOS_API_URL: https://api.khaos.exordex.com
  run: |
    python3 -m pip install khaos-agent
    khaos ci my-agent --eval security --sync

Generate project tokens from the Tokens page in your project on the Dashboard. See the CI/CD docs for full setup instructions.

Badge Generation

Dashboard