# runstate

> Coordination infrastructure for agent swarms: shared work, rate limits, budgets and completion decisions across every agent, process and machine. A hosted service with TypeScript and Python SDKs over one HTTP API. Currently a private, invite-only developer preview — free, no SLA.

runstate does not run your agents, call your models, or proxy your traffic. Your agents keep running wherever they already run; they check in with runstate to claim work, share limits, reserve budget and agree on results. See [/llms-full.txt](https://getrunstate.com/llms-full.txt) for the fuller reference (exact SDK snippets, every primitive, error codes, limits).

## What runstate is

- [Homepage](https://getrunstate.com/): the full pitch, feature walkthroughs and a runnable code example.
- [Contact](https://getrunstate.com/contact): email hello@getrunstate.com.
- [Pricing](https://getrunstate.com/pricing): plans metered on operations, never per agent; free during the developer preview.
- [Request preview access](https://getrunstate.com/request-access): access is invite-only during the developer preview; this form is the only way in today.
- [Documentation](https://docs.getrunstate.com/): guides in buyer order, the TypeScript and Python SDK reference, the HTTP API reference, errors and limits.

## Quickstart

Install:

```bash
npm install runstate-sdk
```

```bash
pip install runstate-sdk
```

TypeScript — claim exclusive ownership of a key so only one agent works on it at a time:

```ts
import { Runstate } from 'runstate-sdk';

const rs = new Runstate(); // reads RUNSTATE_API_KEY / RUNSTATE_SPACE_ID / RUNSTATE_BASE_URL
const run = await rs.scopes.create(); // one run of your swarm

await run.claim('company:acme').run(async () => {
  await researchCompany('acme');
});
```

Python — the same call, async:

```python
from runstate import AsyncRunstate

rs = AsyncRunstate()
run = await rs.scopes.create()

await run.claim('company:acme').run(research_company)
```

Full quickstart (producer + worker, both languages): [/llms-full.txt](https://getrunstate.com/llms-full.txt#quickstart).

## Core concepts, in the order most teams reach for them

- **Work** — claims give exclusive, auto-expiring ownership of a key; shared/joinable tasks let many callers ask for the same work and all receive its one durable result; a dead worker's claim expires and another agent takes over.
- **Capacity** — shared quotas (the SDK calls them allowances) and concurrency pools cap what the whole swarm draws from a resource at once, with fair waiting instead of retry storms; admission takes everything a task needs (pool units, quota units, a work-limit slot) atomically, all or nothing.
- **Budgets** — reserve spend before an expensive call, settle the actual cost, release the rest; a hard ceiling shared by every agent, in exact decimal amounts.
- **Completion and cancellation** — task groups decide once that a run is done (first accepted result, N accepted, or all finished) and stop handing out work in that same step; cancelling a run refuses new work immediately, for the whole subtree.
- **Observability** — the console and the events/watch API show who owns each task, what is waiting, quota and budget levels, and every takeover or decision.

## SDK and API reference

- TypeScript SDK: `runstate-sdk` on npm (Node ≥ 22). Primary classes: `Runstate`, `ScopeHandle`, `ClaimRef`/`ClaimLease`, `MailboxRef`, `TaskTicket`, `PoolRef`, `AllowanceRef`, `BudgetRef`/`BudgetReservation`, `GroupsAPI`/`GroupHandle`, `BarriersAPI`, `TimersAPI`, `EventsAPI`.
- Python SDK: `runstate-sdk` on PyPI (`pip install runstate-sdk`, imports as `runstate`, Python ≥ 3.10). Same concepts, snake_case, both an async (`AsyncRunstate`) and blocking (`Runstate`) facade.
- HTTP API: [https://api.getrunstate.com/openapi.yaml](https://api.getrunstate.com/openapi.yaml) — full OpenAPI document. Public, unauthenticated endpoints live under `/public/v1` (e.g. preview-access requests); everything else needs `Authorization: Bearer <RUNSTATE_API_KEY>`.

## Errors and retries

Every error is `{"error":{"code","message","requestId"}}`. Typed exceptions in both SDKs; the transport layer retries transport failures only (network errors/timeouts, default 2 retries), never a well-formed error response. `.acquire({wait:true})` on claims and pools, and `.take({wait:true})` on quotas, wait and retry the specific busy/exhausted codes for you. Full table: [/llms-full.txt](https://getrunstate.com/llms-full.txt#errors).

## Limits and plans

Free during the developer preview: 100,000 operations/month (hard stop), 10 agents working at once, 2 spaces, 7-day data retention, 64 KiB per message. No self-serve billing yet. Full table: [/llms-full.txt](https://getrunstate.com/llms-full.txt#limits).

## More

- [/llms-full.txt](https://getrunstate.com/llms-full.txt): the fuller reference — every primitive, exact SDK snippets, error codes and limits, and what runstate never claims.
- [/index.md](https://getrunstate.com/index.md): this homepage's content as plain markdown.
- [/sitemap.xml](https://getrunstate.com/sitemap.xml), [/robots.txt](https://getrunstate.com/robots.txt)