Forensic recorder for agentic software

AgentRail

The flight recorder for AI agents. Trace decisions, tool calls, evidence, and spend before an agent becomes impossible to explain.

Explore the guided demoView source
Real Trace Rail screenshot showing the AgentRail forensic dashboard
Actual seeded M1 dashboard state

How evidence moves

AgentRail keeps cost and action proof out of the SDK hot path, then rebuilds the run for investigation.

  1. Instrument

    Add the TypeScript SDK around a trace and let spans inherit actor context unless a tool overrides it.

  2. Accept

    The ingestion endpoint returns 202 only after a fast enqueue, while worker jobs handle durable processing.

  3. Price

    Workers compute cost_usd from the shared catalog. Unknown model pricing stays null and explicit.

  4. Investigate

    The dashboard reconstructs Trace Rail, Action Ledger, and payload evidence through backend routes.

Built for AWS-native deployment

The local M1 stack maps directly to AWS services without changing AgentRail's core contract.

Ingest
API Gateway and Lambda accept spans with HMAC API keys.
Buffer
SQS keeps ingestion fast while workers process traces.
Store
RDS/PostgreSQL stores metadata and S3 stores redacted evidence.
Observe
CloudWatch tracks queue health, worker failures, and latency.
Extend
Amazon Bedrock cost and audit integrations fit the same model catalog path.

Planned AWS path: API Gateway, Lambda, SQS, RDS/PostgreSQL, S3, CloudWatch, and Amazon Bedrock cost metadata.

Published on npm

Install AgentRail with npm

Copy the scoped package names from here. AgentRail is published on npm under @agentrail-sdk; the unscoped agentrail package is not this project.

Available today
SDK, Context CLI, MCP reader
Published packages
@agentrail-sdk/contracts@0.1.1, @agentrail-sdk/db@0.1.0, @agentrail-sdk/sdk@0.1.0, @agentrail-sdk/context@0.1.1, @agentrail-sdk/cli@0.1.1, @agentrail-sdk/mcp@0.1.2
SDK path
npm install @agentrail-sdk/sdk for TypeScript AI applications
Context CLI
npm install -D @agentrail-sdk/cli for local Context Packs
MCP path
npx -y @agentrail-sdk/mcp for read-only trace inspection
MCP Context profile
npx -y @agentrail-sdk/mcp --profile context for local Context Relay tools

Current boundary: SDK recording, local Context CLI packs, and read-only MCP forensic inspection. MCP Context profile 0.1.2 is published on npm for MCP-capable local agent clients.

Live npm commands

Use these exact package names
SDK packagenpm install @agentrail-sdk/sdk

Add AgentRail tracing to a TypeScript AI application.

Context CLInpm install -D @agentrail-sdk/cli

Install the local Context Relay command in a project.

Create Context Packnpx -y @agentrail-sdk/cli context --root . --task "Audit this change" --token-budget 4000 --json

Fetch a bounded local context pack before an AI coding run.

MCP trace readernpx -y @agentrail-sdk/mcp

Open read-only trace lookup from Codex-style tools.

MCP Context profilenpx -y @agentrail-sdk/mcp --profile context

Expose Context Relay tools to MCP-capable local agents.

import { AgentRail, BufferedDelivery, HttpSpanTransport } from "@agentrail-sdk/sdk";

const delivery = new BufferedDelivery({
  transport: new HttpSpanTransport({
    endpoint: "http://localhost:3001/v1/spans",
    apiKey: process.env.AGENTRAIL_API_KEY!,
  }),
});

const rail = new AgentRail({
  actor: { agentId: "research-agent", onBehalfOf: "user_42" },
  sink: delivery,
});

await rail.trace({ name: "research.answer" }, async (trace) => {
  await trace.span(
    {
      kind: "llm",
      name: "draft",
      model: "test.known",
      inputTokens: 1_000,
      outputTokens: 500,
    },
    async () => undefined,
  );
  await trace.action({ name: "filesystem.read" }, async () => undefined);
});

await rail.shutdown({ timeoutMs: 5_000 });

Founding tester program

AgentRail needs three developer teams to test real agent workflows: one SDK integration, one local dashboard review, and one MCP reader workflow.

About and contactFounding tester details

Open-source first, self-hosted by default

Run AgentRail locally, inspect recorded agent behavior, and keep sensitive evidence under your control.

View sourceReview quickstart