Quickstart

Instrument one tool call, run your agent, and inspect the timeline in the BinSentry console.

1. Install

npm i @binsentry/sdk
# or
pip install binsentry

2. Initialize

import { BinSentry } from "@binsentry/sdk";

export const bs = new BinSentry({
  apiKey: process.env.BINSENTRY_KEY!,
  tenant: "acme",
  serviceName: "research-agent",
});

3. Wrap a tool call

import { bs } from "../binsentry";

export async function search(q: string) {
  return bs.run("web.search", async (run) => {
    const results = await fetchResults(q);
    await run.bin.create("search.results", {
      ttl: "90s",
      sensitivity: "public",
      data: results,
    });
    return results;
  });
}

That's it. Open the console and you'll see the run, the bin, and its policy checks.

Concepts

The handful of ideas worth learning before everything else.

Bin

A typed container for an ephemeral artifact. Every bin has an id, content hash, TTL, sensitivity, and tags.

TTL

How long a bin is considered fresh. Reads after TTL expiry are blocked (or refetched) by the freshness gate.

Provenance

The chain of producers and parent bins behind a given bin. Used for replay and audit.

Sensitivity

A label (public / internal / restricted) used by policies to enforce redaction, residency, and access.

Events

Every bin operation becomes a typed event.

• bin.created
  Bin written for the first time.
• bin.read
  Existing bin consumed by a tool.
• bin.written
  New version of an existing bin.
• bin.diffed
  Two bin versions compared in a run.
• bin.expired
  Bin garbage collected past TTL.

OpenTelemetry integration

Bin events are emitted as standard OTel spans with a stable attribute schema. Pipe them anywhere.

import { BinSentry } from "@binsentry/sdk";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";

const tracer = new NodeTracerProvider();
tracer.register();

new BinSentry({
  tenant: "acme",
  serviceName: "research-agent",
  otel: { tracer: "binsentry" },
});

Attributes: binsentry.bin.id, binsentry.bin.ttl, binsentry.bin.sensitivity, binsentry.policy.status.

Policy examples

Illustrative — not the full policy reference.

policies:
  - name: freshness.search
    match: { tag: search }
    require: { age_lt: 90s }
    on_fail: refetch

  - name: residency.eu
    match: { sensitivity: restricted, tenant: eu-* }
    require: { region_in: [eu-west-1, eu-central-1] }
    on_fail: block

  - name: redaction.pii
    match: { sensitivity: internal }
    apply:
      redact: [email, ssn, phone]