Artifacts & Runs

Khaos stores run artifacts under ~/.khaos/runs (or KHAOS_STATE_DIR). These files are the source of truth for debugging, comparisons, and cloud sync.

Artifact Files

FileDescription
manifest-<run_id>.jsonRun provenance (seed, versions, hashes, metadata)
trace-<run_id>.jsonTrace payload for the run
metrics-<run_id>.jsonEvaluation report and scores
llm-events-<run_id>.jsonlLLM call telemetry events (when captured)
stderr-<run_id>.logCaptured stderr (when available)

Inspect Paths Quickly

Terminal
# Resolve artifact paths for a run
khaos artifacts <run-id>

# JSON output (easy to script)
khaos artifacts <run-id> --json

Export a Portable Bundle

khaos export combines local artifacts into a single JSON payload.

Terminal
# Print to stdout
khaos export <run-id>

# Write to file
khaos export <run-id> --out ./run-export.json

# Exclude stderr text
khaos export <run-id> --no-stderr --out ./run-export.json

Programmatic Manifest APIs

Python
from khaos.artifacts import RunManifest, generate_run_id, write_manifest, load_manifest

run_id = generate_run_id("pack")
manifest = RunManifest(run_id=run_id, execution_mode="pack", seed=12345)
write_manifest(manifest)

loaded = load_manifest(run_id)
print(loaded.run_id if loaded else "not found")

Storage Location

Terminal
# Default
~/.khaos/runs/

# Override
export KHAOS_STATE_DIR=/data/khaos
# -> /data/khaos/runs/

Cloud Upload

Terminal
# Upload all pending runs
khaos sync

# Upload one run
khaos sync --run <run-id>

# Upload and remove local files after success
khaos sync --cleanup
No khaos runs Command
Use khaos compare --recent to list recent runs and khaos artifactsto inspect files for a specific run.

Related