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 sync --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 sync --login

# Check authentication status
khaos sync --status

# Logout and clear credentials
khaos sync --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 sync --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 sync --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 sync --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: Test Agent
  env:
    KHAOS_TOKEN: ${{ secrets.KHAOS_TOKEN }}
  run: |
    khaos ci <agent-name> --sync

Generate project tokens in the Dashboard under API Tokens.

CI/CD Integration

Dashboard