Docs

TrustRail is self-hosted — there is no shared public API to call yet. Run the stack locally with the commands below, then integrate against your own running instance.

1. Run it locally

pnpm install --frozen-lockfile
pnpm setup:local     # local Postgres, roles, migrations, signing key, .env
pnpm dev             # api :4000, merchant sandbox :4100, web :3000
pnpm demo:seed       # seeds a demo org, agents, and grants

No Docker required for local dev — a real Postgres instance is provisioned automatically. A Docker Compose deployment path is also available and verified end to end.

2. Call it from an agent

import { TrustRail } from "@trustrail/sdk";

const client = new TrustRail({
  baseUrl: "http://localhost:4000",
  apiKey: process.env.TRUSTRAIL_API_KEY!, // scoped to one agent + environment
});

const action = await client.actions.execute({
  grantId: process.env.TRUSTRAIL_GRANT_ID!,
  connectorId: "merchant_sandbox",
  action: "refund.create",
  resourceId: "order_demo_101",
  arguments: { amount_minor: 8000, currency: "EUR", reason: "Return" },
  idempotencyKey: "demo-refund-001",
});

switch (action.decision) {
  case "DENY":
    console.log("denied:", action.reason_codes);
    break;
  case "REQUIRE_APPROVAL": {
    const result = await client.actions.wait(action.action_id, { timeoutMs: 60_000 });
    console.log("resolved to:", result.decision, result.execution_state);
    break;
  }
  case "ALLOW": {
    const result = await client.actions.wait(action.action_id, { timeoutMs: 30_000 });
    console.log(result.execution_state === "succeeded" ? "refunded" : result.execution_state);
  }
}

A Python SDK and an MCP stdio adapter expose the same actions.execute / actions.wait / receipts.verify surface.

Reference docs

These live as Markdown files in the repository under docs/ — open them directly from a checkout.

API reference

Every route, request, and response shape.

docs/API.md

SDK quickstart

TypeScript and Python, side by side.

docs/SDK_QUICKSTART.md

MCP setup

Wire the MCP adapter into a real MCP client.

docs/MCP_SETUP.md

Architecture

How the gateway, policy engine, and connectors fit together.

docs/ARCHITECTURE.md

Threat model

What this does — and does not — protect against.

docs/THREAT_MODEL.md

Operations

Runbook: backups, key rotation, restore.

docs/OPERATIONS.md

Already have it running and signed in? Open the in-app Developers page for copyable samples using your own sandbox credentials.