Quickstart | AgentMargin

Fastest path: the demo

With OrbStack or Docker Compose, Node.js 22.18+ and npm, one command builds the dashboard, starts a localhost-only PostgreSQL, applies migrations and seeds three fictional customers.

bash

git clone https://github.com/rzkarsyad/agentmargin.git
cd agentmargin
npm ci
npm run demo

Copy the AgentMargin API key it prints and open http://127.0.0.1:8787/dashboard. Pick a period that includes today's UTC date. No OpenAI account is needed. Stop with Ctrl+C, then npm run demo:stop.

Prefer to set it up by hand? Follow the steps below.

1. Run the cost engine

No database needed. Requires Node.js 22.18+ (24 recommended).

bash

git clone https://github.com/rzkarsyad/agentmargin.git
cd agentmargin
npm ci
node --experimental-strip-types examples/calculate-margin.ts
npm run check

This uses fictional USD token rates and a simulated customer. It doesn't contact OpenAI.

2. Start a local PostgreSQL

Optional. With OrbStack or Docker installed:

bash

docker run -d --name agentmargin-local \
  -e POSTGRES_USER=agentmargin \
  -e POSTGRES_PASSWORD=local-dev-only \
  -e POSTGRES_DB=agentmargin \
  -p 127.0.0.1:55432:5432 postgres:16

export DATABASE_URL='postgresql://agentmargin:local-dev-only@127.0.0.1:55432/agentmargin'

Apply the migrations in order. You need a working psql client.

bash

psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f db/001_initial.sql
psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f db/002_ingestion.sql
psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f db/003_revenue_ingestion.sql
psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f db/004_workspace_pricing.sql
psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f db/005_api_key_roles.sql
psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f db/006_api_key_expiry.sql

3. Create a workspace and key

On macOS or Linux with uuidgen:

bash

export WORKSPACE_ID="$(uuidgen | tr '[:upper:]' '[:lower:]')"
psql "$DATABASE_URL" -c "INSERT INTO workspaces(id,name) VALUES ('$WORKSPACE_ID','Local demo');"
node --experimental-strip-types apps/api/src/create-key.ts "$WORKSPACE_ID"

The AgentMargin key is shown once. Store it in a password manager and never commit it.
It isn't your OpenAI key. Don't mix the two up.
New keys expire after 90 days by default. The CLI accepts an optional 1–365 day TTL after the access role.

4. Start the API and dashboard

bash

npm run build:web
npm run start -w @agentmargin/api

Open http://127.0.0.1:8787/dashboard on the same machine and paste the key. It isn't saved to browser storage. Then submit usage and revenue from server-side TypeScript:

import { AgentMarginClient } from './packages/sdk/src/index.ts';

const client = new AgentMarginClient({
  endpoint: 'http://127.0.0.1:8787',
  apiKey: process.env.AGENTMARGIN_API_KEY!,
});

await client.track([{
  id: 'demo-usage-1', customerId: 'demo-customer', model: 'example-model',
  occurredAt: new Date().toISOString(), inputTokens: 1000, outputTokens: 200,
}]);

await client.trackRevenue([{
  id: 'demo-invoice-1', customerId: 'demo-customer',
  occurredAt: new Date().toISOString(), amountMicros: '29000000',
}]);

5. Shut it down

Stop the API with Ctrl+C. If you created the container only for this and don't need its data:

bash

docker rm -f agentmargin-local

Scope

AgentMargin ships no TLS gateway, database RLS, distributed limiter, backup and restore procedure, or production-readiness guarantee.

OpenAI integration Demo guide on GitHub