AgentLedger docs

Self-host or run a private invite-only control plane with BYOK (bring your own provider keys). Live console is /app (Clerk). SaaS subscriptions are deferred — installs unlock full entitlements without Stripe. Optional local /demo exists only when AGENTLEDGER_DEMO_MODE=true.

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 (recommended):
#   AGENTLEDGER_DEMO_MODE=false
#   NEXT_PUBLIC_CLERK_INVITE_ONLY=true
#   + Clerk keys

pnpm install
pnpm db:migrate
pnpm db:seed   # optional sample 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

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. /sign-up shows “Invite only” when the flag is on.

Invite users from your machine (never commit CLERK_SECRET_KEY):

# Load CLERK_SECRET_KEY from apps/web/.env.local
pnpm invite -- [email protected]
pnpm invite -- [email protected] [email protected]

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.

Alert HTML embeds a static PNG logo from /brand/email-logo.png (served from NEXT_PUBLIC_APP_URL). Email clients often fail on SVG or Next.js dynamic icon routes.

7. Hard budgets

Create a monthly project budget. When spent ≥ amount on a hard budget, the proxy returns HTTP 402. Self-host installs unlock hard budgets without a paid plan.

8. Billing (deferred)

Stripe Checkout / Customer Portal are not offered yet. Entitlements are unlocked for self-host. Webhook and checkout code remain in the repo but inert unless you set AGENTLEDGER_BILLING_ENABLED=true plus Stripe price/secret vars on a paid host. Leave that flag unset on self-host and on Railway smoke. Reactivation steps: DEPLOY.md and scripts/stripe-sandbox.md.

9. Open source

AgentLedger is MIT-licensed. Self-host is free; hosted monetization is an optional deployment flag, not a license restriction. See the repo LICENSE and CONTRIBUTING.md.

Deploy notes: DEPLOY.md. Railway: public app service, private Postgres; ship via GitHub merge → auto-deploy.