# Stoke

> One control point for every call your agents make. A single ~5.5 MB Rust binary that sits between AI agents and the model APIs they call, and enforces policy at the request path: hard per-key budget caps, rate limits, and a semantic loop breaker — all checked *before* a provider is contacted. It also routes local-first across your own machines. MIT licensed, pre-release, EU-based.

Stoke is an enforcement gateway, not an observability tool. Dashboards report what happened; Stoke decides what is allowed to happen. Requests that exceed a budget or trip the loop breaker are refused with `429`, never forwarded.

## Facts an agent needs before using it

- Default listen address: `127.0.0.1:8787`. Config file: `stoke.toml` (TOML).
- **Fail-closed:** with no `STOKE_API_KEYS` set and no `STOKE_DEV=1`, every request is rejected. This is intentional. Every endpoint except `GET /health` requires `Authorization: Bearer <key>`.
- OpenAI-compatible clients: set `OPENAI_BASE_URL=http://127.0.0.1:8787/v1`.
- Claude Code: set `ANTHROPIC_BASE_URL=http://127.0.0.1:8787` (uses `POST /v1/messages`, which forwards to a configured `anthropic` provider — it does **not** translate Anthropic requests onto local models).
- Stoke ships with **no model names**. Models come from your config or are discovered on your own Ollama nodes.

## Endpoints

- `GET /health` — liveness. The only unauthenticated endpoint.
- `POST /v1/chat/completions` — OpenAI-compatible, SSE streaming and `tool_calls` supported.
- `POST /v1/messages` — Anthropic Messages API, enforced passthrough.
- `GET /v1/nodes` — live registry: per-node health, pulled/warm models, in-flight count, measured latency.
- `GET /v1/budget` — per-key spend and limits, plus the savings receipts ledger.
- `GET /v1/models`, `GET /v1/pricing`, `GET /v1/cache`, `GET /v1/routes`.

## Install

```sh
curl -sSf https://stokegate.com/install | sh -s -- --version nightly
```

Static binaries (macOS arm64/x64, Linux x64/arm64) are built from every commit and published to a rolling `nightly` prerelease. No stable tag exists yet; a bare `| sh` resolves `latest` and will compile from source instead.

## Guides

Task-shaped walkthroughs, each verified against the running binary: https://stokegate.com/guides/

## Docs

- [README](https://github.com/Ozperium/stoke/blob/main/README.md): what it does today, quickstart, endpoint table, scope limits.
- [Architecture](https://github.com/Ozperium/stoke/blob/main/ARCHITECTURE.md): the exact request pipeline, node registry, federation, failure semantics.
- [Routing design](https://github.com/Ozperium/stoke/blob/main/docs/design/routing.md): placement scoring, auto-routing, hedged dispatch.
- [Agent skill](https://github.com/Ozperium/stoke/blob/main/skills/stoke/SKILL.md): a runnable procedure for putting an agent behind Stoke.
- [Contributing / working in the repo](https://github.com/Ozperium/stoke/blob/main/AGENTS.md): build, test, and the invariants that must hold.

## Scope limits (do not claim otherwise)

- Subscription plans (Claude Max/Pro, ChatGPT Plus) have no per-request dollar price. Stoke can rate-limit and loop-kill that traffic; it **cannot** dollar-cap it. Hard USD caps apply to metered API keys.
- Streamed and non-streamed responses both accrue spend; a stream is billed when it ends, from the usage the provider reports. If a metered provider reports none, spend is estimated and flagged. Loop detection, rate limits, and auth still cover streaming traffic.
- No published performance benchmarks yet. Reproducible harnesses live in `scripts/`.