AgentMargin v0.2.0-alpha

AgentMargin v0.2.0-alpha

Experimental open-source release — localhost-only, not production-ready.

AgentMargin helps developers attribute AI inference costs and revenue to customers so they can understand which customers create or consume AI contribution. This alpha focuses on developer experience, trusted accounting semantics and verifiable local testing.

Highlights

Run a local demo with one command

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

Requires Node.js 22.18+ and OrbStack/Docker Compose. The script starts a localhost-bound PostgreSQL container, applies migrations, seeds synthetic usage/revenue and prints a new local workspace API key. Open http://127.0.0.1:8787/dashboard and select a period covering today. The demo includes one profitable customer, one loss-making customer and one whose cost is unknown.

Stop the API with Ctrl+C; stop the demo container with npm run demo:stop. Demo reset requires explicit confirmation and deletes synthetic demo data. See docs/DEMO.md.

Track completed OpenAI requests

The source-first TypeScript SDK adds one-call post-response metering helpers for OpenAI Responses and Chat Completions:

await margin.trackOpenAIResponse(response, trustedCustomerId);

These map token/model metadata only and do not send prompts, outputs, or OpenAI credentials to AgentMargin. They reject missing usage rather than assuming zero cost. A Next.js integration recipe and a synthetic SDK example are included. The SDK is not yet published on npm and automatic instrumentation is not implemented.

Understand unknown costs

Authenticated analytics adds a per-model unknown-event count for the selected workspace and time range. The dashboard displays up to 20 affected models with a truncation notice. Model strings are safely rendered as text, not HTML. Adding a price later does not silently alter historical events. See docs/UNKNOWN_COSTS.md.

Stronger end-to-end checks

GitHub Actions now exercises a complete disposable Docker PostgreSQL → localhost authenticated API → SDK → real Chromium dashboard workflow on desktop and mobile, in addition to TypeScript, unit tests, PostgreSQL concurrency, npm audit, a heuristic credential scan and mocked-API browser tests.

The maintainer also confirmed the local demo in OrbStack and the synthetic SDK integration on October 22, 2026, including expected revenue/costs and unknown-cost diagnostics.

Compatibility

• Node.js 22.18+ (24 recommended), npm.
• PostgreSQL 15+ for the API; the one-command demo uses Docker PostgreSQL 16.
• This alpha remains a source-first monorepo. Core and SDK are not released as stable registry packages.
• Existing database migrations are unchanged; no production migration or deployment upgrade is offered.

Known limitations

• No automatic provider model price catalog or provider invoice reconciliation; do not infer missing costs as zero.
• Contribution includes tracked inference costs only, not full gross or net profit.
• No production reverse proxy/TLS, multi-instance rate limiting, PostgreSQL RLS, audited backup/restore, privacy lifecycle, or independent penetration test.
• Browser E2E covers local synthetic data; no real customer traffic or production service is certified.
• Current dashboard remains a localhost-oriented preview with bounded customer and model diagnostics.

Use synthetic data only. Do not deploy this alpha to the public internet. Review SECURITY.md.

Feedback and contributions

Feedback from AI SaaS developers, independent setup attempts, reproducible bugs and security reports are appreciated. See the contributing guide, roadmap, and early-adopter issue.

Prior release: v0.1.0-alpha.