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 · /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
• Human approval · typed BusinessImpact + action_digest action-bound grants
• Error handling · ErrorContext, multi-layer fail-CLOSED

How-to

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

Reference

• SDK API · @protect (canonical), @sensitive(impact=...) (advanced), workflow, exceptions
• HTTP API · /track, /gate, /capabilities, /heartbeat, WebSocket
• Error codes · validation_error, RateLimitError, kill contract

Compliance

• Overview · geo-block and sanctions-screening posture
• 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.

Deployment

Two parallel workflows ship from this repository. Until DNS is cut over, traffic flows through the active origin (GitHub Pages); the standby origin (Cloudflare Pages) stays current on every push so the switchover is a one-record change at the registrar.

Workflow	Target	DNS origin	Status
.github/workflows/docs.yml	GitHub Pages	nullrunio.github.io (CNAME at netim.net)	Active
.github/workflows/pages-cf.yml	Cloudflare Pages	<project>.pages.dev (CF-provisioned)	Standby

Current security posture

Mozilla Observatory scores each header in the response:

Test	GitHub Pages (current)	Cloudflare Pages (after cutover)
Content-Security-Policy	passes (meta-tag form)	passes (HTTP header)
Referrer-Policy	passes (meta-tag form)	passes (HTTP header)
Strict-Transport-Security	❌ (GitHub Pages forbids)	✅ (1 year, includeSubDomains)
X-Content-Type-Options	❌	✅ nosniff
X-Frame-Options	❌	✅ DENY
Permissions-Policy	❌	✅ (camera, mic, geo, etc. disabled)
Cross-Origin-Opener-Policy	❌	✅ same-origin
Cross-Origin-Resource-Policy	❌	✅ same-origin

GitHub Pages does not allow custom HTTP response headers — the <meta http-equiv> form in overrides/main.html covers the two tests that accept it; the remaining six tests require the HTTP-header form in docs/_headers, which only Cloudflare Pages can serve. See the comment block at the top of docs/_headers for the per-header credit map.

One-time cutover procedure

1. In the Cloudflare dashboard, create a Pages project pointing at this repo, branch master, build command mkdocs build --strict, output directory site/.
2. Add the custom domain docs.nullrun.io to the project. Cloudflare issues the certificate and shows the target CNAME (<project>.pages.dev).
3. Add two GH repository secrets: CLOUDFLARE_API_TOKEN (Pages Edit permission) and CLOUDFLARE_ACCOUNT_ID (from the CF dashboard URL).
4. At the registrar (netim.net), change the CNAME record for docs.nullrun.io from nullrunio.github.io. to the <project>.pages.dev. value CF provided. DNS propagation: ~5 min on Fastly's resolver, up to 48 h elsewhere.
5. Re-run the Mozilla Observatory scan. Expected grade: A+.
6. After the cutover, disable .github/workflows/docs.yml to stop the duplicate GitHub Pages deploy.

The <meta http-equiv> tags in overrides/main.html stay in place as a defence-in-depth fallback — they have no effect when the equivalent HTTP headers are present, and they keep the site partially hardened if the site ever has to fall back to a host without header injection.

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)