Docs — Runhalt

Prerequisites

Go installed. From the repo root, make build produces bin/fuse (Runhalt server) and bin/mockprovider.

Start

Terminal 1 — mock provider. Terminal 2 — Runhalt pointed at it:

make run-mock
make run-fuse
# → http://127.0.0.1:8080/healthz → ok

Virtual key

Create a key with a dollar budget. The agent uses this token — not your OpenAI key.

curl -s -X POST http://127.0.0.1:8080/v1/admin/keys \
  -H "X-Fuse-Admin-Token: dev-admin" \
  -H "Content-Type: application/json" \
  -d '{"name":"demo","budget_usd":1.00}'

Halt mid-run

Reuse the same X-Run-Id. After N successful calls, the next one returns 409.

TOKEN=sk-rh-…
curl -s http://127.0.0.1:8080/v1/chat/completions \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Run-Id: demo-run" \
  -H "X-Fuse-Run-Max-Calls: 5" \
  -H "Content-Type: application/json" \
  -d '{"model":"mock-gpt","stream":false,"messages":[{"role":"user","content":"hi"}]}'

Dashboard

Lab — try chat / runaway kill without curl
Overview — spend, calls, kills, 402s
Keys — create / disable virtual keys
Onboarding — paste a provider key (hosted mode)

Open /app. Self-host admin token default: dev-admin.

Real provider

Point Runhalt at OpenAI and set -provider-key. Full checklist: REAL_TEST.md or ./scripts/dogfood.sh openai.

./bin/fuse \
  -listen :8080 \
  -upstream https://api.openai.com \
  -provider-key "$OPENAI_API_KEY" \
  -admin-token dev-admin \
  -fail-open=false

Then in the agent: OPENAI_BASE_URL=http://127.0.0.1:8080/v1 and OPENAI_API_KEY=sk-rh-….

Hosted

Production: https://runhalt.com · dashboard /app. Env vars still use the FUSE_* prefix for compatibility.