AgentLedger docs

Self-host or run an invite-only hosted control plane with BYOK (bring your own provider keys). The public Railway site is docs plus a seeded demo at /demo. Live console is /app (Clerk). Stripe tiers are deferred while on BYOK.

1. Quick start (self-host)

git clone https://github.com/a-n-oss/AgentLedger.git
cd AgentLedger
docker compose up -d

cp apps/web/.env.example apps/web/.env.local

# Required for BYOK encryption (hosted or multi-project):
#   openssl rand -base64 32  →  AGENTLEDGER_SECRETS_KEY=

# Self-host single-tenant fallback (optional if you use BYOK UI):
#   OPENAI_API_KEY=sk-...

# Invite-only hosted auth:
#   AGENTLEDGER_DEMO_MODE=false
#   NEXT_PUBLIC_CLERK_INVITE_ONLY=true
#   + Clerk keys

pnpm install
pnpm db:migrate
pnpm db:seed   # optional demo charts
pnpm dev       # http://localhost:3000

2. Hosted BYOK (safest token keys)

Do not put customer OpenAI keys in server env and redeploy. Each project stores its own key encrypted at rest.

Set a master key (32 bytes, base64):

# Generate once per environment — never commit
openssl rand -base64 32
# Paste into apps/web/.env.local as AGENTLEDGER_SECRETS_KEY=...

Open a project → Provider keys (BYOK) → paste xAI / OpenAI / Anthropic / Google key → Save. Only a hint like …abcd is shown afterward. Models containing grok auto-route to xAI (https://api.x.ai/v1).
Proxy resolves keys in order: project BYOK → then optional env fallback for single-tenant self-host.
Revoke in the UI anytime — no redeploy.

3. Invite-only sign-up (hosted)

For a private hosted instance, disable public registration in Clerk and set:

AGENTLEDGER_DEMO_MODE=false
NEXT_PUBLIC_CLERK_INVITE_ONLY=true

In Clerk Dashboard: User & authentication → restrict sign-ups / use invitations only. Invite users by email; /sign-up shows “Invite only” when the flag is on.

4. Self-host env fallback

Single-tenant installs can skip the BYOK UI and set XAI_API_KEY / OPENAI_API_KEY (and/or Anthropic / Google) on the server. Prefer BYOK when multiple teams share one AgentLedger.

5. Create a project + AgentLedger API key

In Projects, copy the al_live_… key (shown once). That key authenticates agents to your AgentLedger — it is not the OpenAI key.

import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: process.env.AGENTLEDGER_API_KEY!,
  baseURL: "http://localhost:3000/api/v1",
  defaultHeaders: {
    "x-al-agent": "support-triage",
    "x-al-team": "support",
  },
});

6. Email budget alerts

Set RESEND_API_KEY and a verified ALERT_FROM_EMAIL in .env.local.
Add an email channel under Alerts.
Click Send test alert (no spend required). Leave INNGEST_EVENT_KEY empty for inline delivery.
For a real threshold: create a tiny soft budget, then POST /api/v1/runs/spans with costUsd large enough to cross it.

7. Hard budgets

Create a monthly project budget. When spent ≥ amount on a hard budget (Pro/Team entitlements), the proxy returns HTTP 402.

8. Stripe subscriptions

Set STRIPE_SECRET_KEY, STRIPE_PRICE_PRO, STRIPE_PRICE_TEAM, and STRIPE_WEBHOOK_SECRET.
Webhook URL: /api/stripe/webhook (checkout completed + subscription updated/deleted).
Enable Customer Portal in the Stripe Dashboard (test mode for smoke).
In Billing, upgrade with test card 4242 4242 4242 4242 — plan should update after the webhook.

Deploy notes: DEPLOY.md.