What is Stoke?
Stoke is a lightweight, self-hosted gateway designed to act as a protective layer between your AI agents and API providers. It prevents runaway costs and infinite loops by enforcing hard budget caps and request-path filtering before any API call is executed.
- Best For: Developers and AI engineers running autonomous agents on metered API keys.
- Pricing: Open source (MIT license).
- Category: AI Automation
- Free Option: Yes ✅
The Problem Stoke Solves
AI agents are powerful, but they are also prone to catastrophic failure modes. A single coding agent caught in a recursive loop at 2:00 a.m. can burn through hundreds or thousands of dollars in API credits before a human wakes up to check the dashboard. Current billing alerts are essentially post-mortems; they notify you after the damage has already occurred.
This problem disproportionately affects developers who rely on autonomous agents for long-running tasks or overnight coding sessions. Traditional dashboards only observe usage after the fact, leaving your wallet vulnerable to misconfigured agents or infinite retry cycles.
Stoke changes the paradigm by acting as a gatekeeper. It intercepts requests at the network level, evaluates them against your defined budget and loop-detection thresholds, and refuses them if they violate your safety parameters. In this tutorial, you'll learn exactly how to use Stoke — step by step.
How to Get Started with Stoke in 5 Minutes
- Download the Stoke binary (a 5.5MB Rust executable) from the official website or repository.
- Create your configuration file, defining your API keys and setting the `[[keys]]` table to establish your hard USD budget caps.
- Set your environment variables, specifically ensuring `STOKE_API_KEYS` is populated with the keys you intend to monitor.
- Point your agent's `base_url` to `localhost:8787/v1` (or `ANTHROPIC_BASE_URL` for Claude Code) to route traffic through the gateway.
- Launch the binary and verify your connection via the `/health` endpoint to ensure the gateway is active and enforcing your rules.
How to Use Stoke: Complete Tutorial
Step 1: Configuring Budget Caps and Rate Limits
The core of Stoke’s utility lies in its configuration table. You must define your keys within the `[[keys]]` section of your configuration file. For each key, you can specify a hard `budget_usd` and a `rate_limit_rpm` to ensure no single agent can exceed your financial or throughput constraints.
When an agent sends a request, Stoke checks these values in real-time. If the request would push the key over its budget, the gateway returns a `429 Budget exceeded` error. This allows your agent to handle the failure gracefully rather than continuing to consume credits.
Step 2: Implementing the Loop Kill Switch
Stoke employs a two-layer circuit breaker to stop agents from looping. It uses exact prompt-hash matching to identify identical requests and an opt-in semantic similarity check to catch agents that rephrase their failing requests. If five similar requests occur within 60 seconds, Stoke blocks the key for 120 seconds.
This feature is active by default, providing an immediate safety net for autonomous coding agents. By preventing these loops at the gateway, you ensure that your API keys are not exhausted by repetitive, non-productive compute cycles.
Step 3: Node-Aware Routing and Local Model Integration
Stoke is designed to work with both cloud providers and local models running on Ollama. By pointing Stoke at your Ollama nodes, the gateway automatically polls for model availability and performance metrics. It prefers warm nodes and balances load based on in-flight counts and latency.
You can use the `auto` model routing to let Stoke decide the best path for your request based on cost, latency, and your preference order. This allows you to offload simple tasks to local hardware while keeping cloud models as a failover option.
Stoke: Pros & Cons
| Pros | Cons |
|---|---|
| Prevents financial damage by stopping requests before they reach the provider. | Requires manual configuration and self-hosting. |
| Lightweight 5.5MB Rust binary with minimal overhead. | Threshold tuning is currently global rather than per-key. |
| Compatible with any OpenAI-style API. | Requires technical expertise to set up and maintain. |
| Self-hosted and private; no data leaves your control. |
Stoke Pricing: Free vs Paid
Stoke is currently released as an open-source project under the MIT license. This means the core software is free to use, modify, and integrate into your own infrastructure. There are no explicit "paid" tiers mentioned in the current documentation, as the project is in a pre-release phase.
Because it is self-hosted, your only costs are the infrastructure you choose to run the binary on and the API usage fees you incur from your chosen providers. As the project matures, it is possible that commercial support or managed versions may appear, but for now, the tool is entirely free to deploy.
👉 Check the latest pricing and licensing updates on the official website.
Who is Stoke Best For?
For AI Engineers: You are managing complex agentic workflows and need a reliable way to enforce guardrails across multiple API keys. Stoke provides the granular control necessary to prevent budget overruns in production environments.
For Solo Developers: You are experimenting with autonomous coding agents like Claude Code or Aider and want to avoid the risk of waking up to a massive, unexpected bill. Stoke acts as an essential insurance policy for your development environment.
For Infrastructure Teams: You need a centralized gateway to manage model routing, load balancing, and cost tracking across your internal hardware and cloud providers. Stoke’s node-aware routing and federation capabilities make it a strong candidate for local-first AI stacks.
Who Should Not Use Stoke?
Stoke is likely overkill if you are a casual user who only makes occasional, manual API calls through a chat interface. If you aren't running autonomous agents that have the potential to loop or consume large volumes of tokens, the overhead of hosting and configuring a gateway may outweigh the benefits.
Additionally, if your team lacks the technical capacity to manage a self-hosted Rust binary or configure network routing, you might find the setup process frustrating. In such cases, relying on the built-in usage limits provided directly by your API provider (e.g., OpenAI’s dashboard limits) might be a simpler, albeit less flexible, alternative.
Alternatives to Stoke
Common alternatives include managed AI gateways like Helicone, LiteLLM, or Portkey, which offer observability and some budget controls. However, Stoke differentiates itself by focusing on a "fail-closed" architecture and a lightweight, self-hosted binary that prioritizes stopping requests before they ever leave your machine. If you need deep integration with local hardware like Ollama and want to avoid third-party SaaS dependencies, Stoke is the superior choice.
How We Evaluated Stoke
This tutorial was compiled based on the official product documentation, the public landing page, and the technical specifications provided by the Stoke project as of July 20, 2026. We analyzed the tool's architecture, feature set, and intended use cases to provide an objective overview for developers. No hands-on testing was performed by our editorial team; the information presented reflects the developer's stated functionality and design philosophy.
Final Verdict: Is Stoke Worth It?
Stoke is a highly effective, specialized tool for anyone serious about running autonomous AI agents without the risk of financial ruin. Its focus on "refusing" rather than "reporting" makes it a must-have for developers who prioritize safety and cost control.