checkrd

Quickstart

Get up and running with Checkrd in under 5 minutes.

Quickstart

Get up and running with Checkrd in under 5 minutes.

1. Install

bash
pip install checkrd
# or
npm install checkrd

2. Create an agent + key

In the dashboard:

  1. Create an agent. Copy the agent ID — it's a UUID like 0193b8b4-1c2d-7e3f-a4b5-c6d7e8f9a0b1, not the human-readable name you gave it. Both are shown on the agent's detail page; the SDK needs the UUID.
  2. Create an API key for your workspace. Copy it.
  3. Publish a starter policy on the agent's Policy tab — the dashboard ships with a default allow-all-GETs / deny-everything-else template you can edit later.

agent_id is a UUID, not a name

Every snippet below uses 01234567-89ab-cdef-0123-456789abcdef as a placeholder. Replace it with the UUID you copied in step 1. Passing the agent's display name (e.g. "my-agent") instead of the UUID makes the SDK fail with "agent not found" at the first request.

3. Wrap your client

The SDK boots, fetches your published policy from the control plane, installs it, and starts enforcing — all from a single call. No local YAML, no policy= argument in your app code.

python
from checkrd import Checkrd
import httpx

checkrd = Checkrd(
    agent_id="01234567-89ab-cdef-0123-456789abcdef",
    api_key="ck_live_...",
)
client = checkrd.wrap(httpx.Client())

# Every request through `client` is policy-evaluated before it
# leaves the machine, signed for telemetry, and logged to your
# dashboard. Use it like the underlying httpx client.
response = client.get("https://api.salesforce.com/services/data/v58.0/sobjects/Contact")
typescript
import { Checkrd } from "checkrd";

const checkrd = new Checkrd({
  agentId: "01234567-89ab-cdef-0123-456789abcdef",
  apiKey: "ck_live_...",
});
await checkrd.ready();          // awaits the bundle fetch + install
const fetch = checkrd.wrap(globalThis.fetch);

// Every request through `fetch` is policy-evaluated, signed for
// telemetry, and logged to your dashboard. Replace the URL below
// with whichever endpoint your agent hits.
const response = await fetch("https://api.salesforce.com/services/data/v58.0/sobjects/Contact");

That's it. Outbound requests now go through your dashboard's published policy. Edit the policy in the dashboard and the SDK picks up the new version over the SSE control channel in milliseconds — no redeploy required.

Server is canonical

The control plane is the source of truth for policy. The SDK boots with a deny-all baseline, fetches the published DSSE-signed bundle from GET /v1/agents/:id/control/state synchronously, and installs it before the wrapped client returns. Same pattern as OPA bundles, Envoy xDS, and LaunchDarkly streaming.

4. Load your API key from the environment

For anything checked into source control, read the key from the environment instead:

python
import os
api_key = os.environ["CHECKRD_API_KEY"]
typescript
const apiKey = process.env.CHECKRD_API_KEY!;

What about local development?

For one-off local testing without the control plane, you can supply a policy directly:

python
# Pure-local: no api_key, no control plane. Use a YAML file or a dict.
client = wrap(
    httpx.Client(),
    agent_id="01234567-89ab-cdef-0123-456789abcdef",
    policy="policy.yaml",
)

Mixing policy= and api_key= is intentionally refused in production — the local policy would silently shadow whatever your dashboard publishes. If you need it for development, opt in explicitly:

bash
export CHECKRD_ALLOW_LOCAL_POLICY=1

Editing your policy

Policies live on each agent in the dashboard. Start in mode: dry_run so decisions are logged to the Events table but no requests are actually blocked. Once the dashboard view matches your intent, flip to mode: enforce.

yaml
mode: dry_run        # logs everything, blocks nothing — flip to enforce later
default: deny

rules:
  - name: read-salesforce
    allow:
      method: [GET]
      url: "api.salesforce.com/**"

  - name: block-mutations
    deny:
      method: [POST, PUT, PATCH, DELETE]
      url: "**"

Enforce mode raises on deny

Once you flip to mode: enforce, denied requests raise CheckrdPolicyDenied (Python) / throw CheckrdPolicyDenied (JS) instead of going out to the network. Catch the exception, or run with enforce=False for log-only behavior. See Error handling.

Next Steps

IntroductionError handling