# runstate

> runstate is the coordination backbone for agent swarms: a hosted service with TypeScript and Python SDKs that keeps shared work, rate limits, budgets and completion decisions consistent across every agent, process and machine. Your agents run on your infrastructure; runstate holds the shared state they check in with.

Install with `npm install runstate-sdk` or `pip install runstate-sdk` (imports as `runstate`). The hosted API is `https://api.getrunstate.com` (set `RUNSTATE_BASE_URL`; the SDKs default to `http://localhost:8080`). Authenticate with `RUNSTATE_API_KEY` and select a space with `RUNSTATE_SPACE_ID`, both from the console at https://app.getrunstate.com. Every page below is plain Markdown; the whole site in one file is at https://docs.getrunstate.com/llms-full.txt. The OpenAPI document is at https://docs.getrunstate.com/openapi.yaml.

Vocabulary: the docs say "run", "work queue" and "shared quota"; the SDKs and HTTP API call these scope, mailbox and allowance (the SDK accessor is `quota`).

## Get started

- [runstate docs](https://docs.getrunstate.com/index.md): runstate is the coordination backbone for agent swarms. Your agents keep running where they run; runstate keeps their shared work, rate limits, budgets and results consistent.
- [Quickstart](https://docs.getrunstate.com/quickstart.md): Submit a durable task from one process, complete it from a worker in another, and read back its recorded result, in TypeScript or Python.
- [Concepts](https://docs.getrunstate.com/concepts.md): Spaces, runs, work queues, tasks, deliveries, claims and leases, and how the names in these docs map to the names in the SDKs and API.
- [Configuration & auth](https://docs.getrunstate.com/configuration.md): Environment variables, client options, API key permissions, worker identity, timeouts and transport retries for the TypeScript and Python SDKs.

## Guides

- [Claims, shared tasks and takeover](https://docs.getrunstate.com/guides/work-once.md): Give one agent ownership of a key, let many callers share one task and its single result, and let another worker take over when one crashes.
- [Quotas and concurrency pools](https://docs.getrunstate.com/guides/share-capacity.md): Give the whole swarm one shared quota or concurrency pool, let agents wait their turn instead of retrying together, and start a task only when everything it needs is available.
- [Spend budgets](https://docs.getrunstate.com/guides/budgets.md): Give the swarm one spend ceiling. Agents reserve before expensive work, settle the actual cost exactly once, and release what they didn't use.
- [Task groups and cancellation](https://docs.getrunstate.com/guides/completion-and-cancellation.md): Decide exactly once when a set of tasks is done (first accepted, N accepted, or all finished), stop handing out work in the same step, and cancel a whole run from one call.
- [Events and monitoring](https://docs.getrunstate.com/guides/observability.md): See the swarm as one system with the console, the event journal, reconnectable watch streams, webhooks and read-only diagnostics.
- [LangGraph and OpenAI Agents SDK](https://docs.getrunstate.com/guides/integrations.md): Add runstate coordination to LangGraph graphs and OpenAI Agents SDK workers without changing how the agents run.

## SDK reference

- [TypeScript SDK](https://docs.getrunstate.com/sdk/typescript.md): Reference for runstate-sdk on npm, the TypeScript SDK for Node.js 22 and later. Every public class, method, option and default.
- [Python SDK](https://docs.getrunstate.com/sdk/python.md): Reference for runstate-sdk on PyPI, the Python SDK for Python 3.10 and later. AsyncRunstate, the blocking Runstate client, every method and default, and where behaviour differs from TypeScript.
- [Low-level client (TypeScript)](https://docs.getrunstate.com/sdk/low-level-client.md): createRunstateClient, a thin promise-per-endpoint client for infrastructure authors, with no lease renewal or waiting helpers. TypeScript only.

## HTTP API reference

- [HTTP API overview](https://docs.getrunstate.com/api.md): Base URL, authentication, idempotency, the error envelope and every resource group of the runstate HTTP API, generated from the OpenAPI document.
- [Runs (scopes)](https://docs.getrunstate.com/api/runs.md): Create, inspect, cancel and complete runs. The API calls a run a scope.
- [Claims](https://docs.getrunstate.com/api/claims.md): Exclusive, leased ownership of a named key inside a run.
- [Tasks](https://docs.getrunstate.com/api/tasks.md): Durable, joinable tasks with one recorded result, plus resource-aware admission.
- [Work queues (mailboxes)](https://docs.getrunstate.com/api/work-queues.md): Work queues and inboxes (mailboxes), and settling the messages delivered from them.
- [Shared quotas (allowances)](https://docs.getrunstate.com/api/quotas.md): Fixed-window shared quotas with durable FIFO waiting. The API calls them allowances.
- [Concurrency pools (permits)](https://docs.getrunstate.com/api/pools.md): Capacity counters (permits) and the leased grants taken from them.
- [Work limits](https://docs.getrunstate.com/api/work-limits.md): Bounds on outstanding admitted work under a run.
- [Budgets](https://docs.getrunstate.com/api/budgets.md): Exact-decimal spend budgets: reserve, settle, void.
- [Task groups](https://docs.getrunstate.com/api/task-groups.md): Collective completion: decide once when N results are accepted, the first is accepted, or all members finish.
- [Barriers](https://docs.getrunstate.com/api/barriers.md): Wait-for-all rendezvous points.
- [Timers](https://docs.getrunstate.com/api/timers.md): Durable wakeups.
- [Events, watch & webhooks](https://docs.getrunstate.com/api/events.md): The event journal, reconnectable long-poll watch, and webhook destinations.
- [Diagnostics, usage & limits](https://docs.getrunstate.com/api/diagnostics.md): Read-only diagnostic views, usage counters and per-space limits.

## Reference

- [Errors & retries](https://docs.getrunstate.com/errors.md): Every runstate error code with its HTTP status, SDK exception class and typical cause, plus exactly what the SDKs retry automatically and what your code must handle.
- [Limits & plans](https://docs.getrunstate.com/limits.md): Plan limits for operations, agents working at once, spaces, active runs and tasks, request rate, payload size and retention, plus per-space limits and hard API bounds.
- [Troubleshooting](https://docs.getrunstate.com/troubleshooting.md): Common symptoms when running agents on runstate, what usually causes them, and where to look.
- [Changelog](https://docs.getrunstate.com/changelog.md): Released versions of the runstate TypeScript and Python SDKs and what changed in each.

## Optional

- [Complete documentation](https://docs.getrunstate.com/llms-full.txt): every page above concatenated into one Markdown file
- [OpenAPI document](https://docs.getrunstate.com/openapi.yaml): the HTTP API contract the reference pages are generated from
- [runstate homepage](https://getrunstate.com/llms.txt): product overview and preview access