developer docs

Run Throne from a repo, package, config, or CI job.

Direct commands, clear config, and exit codes. Everything Throne does, runnable from a terminal or a CI job.

quickstart

Run a server

npx throne run github.com/acme/files-mcp
npx throne run @acme/files-mcp
npx throne run ./mcp.config.json

config

Minimal file

{
  "name": "files-mcp",
  "command": "node",
  "args": ["dist/server.js"],
  "cwd": ".",
  "clients": [
    "claude-code",
    "cursor",
    "chatgpt-desktop"
  ],
  "security": {
    "root": "./fixtures/workspace",
    "failOn": ["critical", "high"]
  }
}

ci gate

Block broken releases

npx throne run ./mcp.config.json \
  --fail-on fail \
  --security-fail-on high \
  --report json \
  --out ./throne-report.json

replay

Reproduce one cell

npx throne replay run_4821 \
  --client cursor \
  --tool read_file \
  --trace traces/cursor-streaming-timeout.json

exit codes

Make CI boring

0PASS

All requested gates passed.

1WARN

Warnings were found and the command was configured to fail on warn.

2FAIL

A client failure, high severity finding, or blocked verdict was produced.