NullRun Docs

Source for the docs.nullrun.io site.

What's inside

• Getting started — install, quickstart, SDK configuration.
• Concepts — how budgets, circuit breaker, control plane, sensitive tools, and workflow context work.
• How-to — recipes for specific frameworks and scenarios (LangGraph, OpenAI Agents, cost cap).
• Reference — full SDK / HTTP API / error codes reference.

Where to start

If you want to...	Open
Try it in 5 minutes	Quickstart
Wire up the SDK for production	Configuration
Track or cap spend	Budgets + Cost cap how-to
Use LangGraph	How-to → LangGraph
Use OpenAI Agents	How-to → OpenAI Agents
Debug 4xx / 5xx responses	Error codes
See the full SDK surface	SDK API reference

Full page list

Getting started

• Install · pip install nullrun, API key, auto-instrumentation
• Quickstart · @protect in 30 lines
• Configuration · env vars, transport options, gRPC status

Concepts

• Circuit breaker · CLOSED / OPEN / HALF_OPEN, PERMISSIVE/STRICT/CACHED fallback modes
• Budgets · v3 contract: /gate pre-flight + server-minted reservation_id + /api/v1/track single commit
• Sensitive tools · fail-CLOSED, always
• Workflow context · nullrun.workflow(...) + nullrun.chain(...) + parent_trace_id multi-agent attachment
• Control plane (WebSocket) · real-time kill / pause / approval_resolved
• API keys · scopes, expires_at, rotation, revocation
• Policies · RateLimit / BudgetLimit / ToolBlock, org vs workflow, aggregation
• Tool policies · glob match, 4 KB cap, union across scopes
• Loop detection · window-based exact-match, trips the breaker
• Anomaly detection · mean + N·σ, Lite / Moderate / Strict
• Human approval · pause + Slack/Email/Webhook fanout

How-to

• Protect a LangGraph agent
• Use with OpenAI Agents
• Set a hard cost cap

Reference

• SDK API · init, @protect, @sensitive, workflow, exceptions
• HTTP API · /track, /gate, /capabilities, /heartbeat, WebSocket
• Error codes · validation_error, RateLimitError, kill contract

Compliance

• Overview · Fortress posture, fail-CLOSED matrix
• Geographic restrictions · IP-level geo-block, sanctioned + high-risk blocklists, VPS runbook
• Sanctions screening · OFAC SDN signup screening, degraded fallback

What you need from us

• API key — create one in nullrun.io → Settings → API keys. You get a nr_live_… public identifier. The SDK transparently obtains the HMAC signing secret via POST /api/v1/auth/verify on first use.
• Python ≥ 3.10 for the SDK.
• Nothing else to read the docs — the site is public.

Other NullRun repositories

• nullrun-sdk-python — Python SDK (pip install nullrun)
• nullrun-examples — runnable examples
• .github — organisation profile, SECURITY / SUPPORT
• nullrun — gateway + dashboard (private repository, access on request)