Identity Layer
Ed25519 keypairs
Each agent generates an asymmetric keypair on first init. The private key is written to .spineforge/agent_key.pem and never transmitted anywhere. The public key is registered with the Spineforge backend.
Spine IDs
The registry assigns a permanent, server-scoped UUID (the Spine ID) on registration. The same agent_name always resolves to the same Spine ID across runs, across machines, across deployments.
JWT assertion flow (RFC 7523)
When an agent needs an access token, it signs a JWT with its private key. The registry verifies the signature against the stored public key and issues a short-lived scoped token. No password, no shared secret.
Credential Brokering
The /credentials/lease endpoint
Agents call spine.lease_credential('openai-api-key') instead of reading from env vars. The registry validates the JWT, checks the agent's allowed scopes, and returns a short-lived working copy of the key.
Why this prevents shadow agents
Raw provider keys must be moved out of env files and shared vaults during onboarding. Once they live only in Spineforge, unregistered agents have no path to a working credential. This migration step is a real onboarding requirement — not a footnote.
Revocation semantics (honest)
Revoking an agent blocks future re-leasing immediately. It does not invalidate a lease copy already issued — most providers don't support natively short-lived scoped keys, so the protection is bounded-lag, not instant. We say this plainly.
Scope Enforcement
Scopes declared at registration
When you call spineforge.init(allowed_scopes=[...]), those scopes are registered with the backend. An agent can only request tokens for scopes it declared at registration time.
JWT claims: sub, aud, scope, iat, exp
Every token carries the agent's Spine ID as sub, the target audience as aud, and allowed scopes as scope claims. Validation is set membership — no partial grants, no runtime escalation.
Agent-to-agent delegation
An agent can request a token targeting another agent's Spine ID in aud. The receiving agent verifies the token locally against a cached JWKS endpoint. No Spineforge roundtrip needed on the receive side.
Observability
OpenLLMetry auto-instrumentation
Spineforge hooks into the OpenTelemetry span lifecycle. LangChain, LangGraph, CrewAI, and AutoGen are auto-instrumented — no code changes to your agent logic. Groq calls are captured at the SDK level.
Runs and Actions
Every spine.run() block generates a Run row. Every LLM call and tool invocation inside it generates an Action row. Both are written to Supabase (Postgres) via the APISink with FileSink fallback.
Cost computed once, stored forever
Cost is calculated at write time from the rate_cards table keyed on (provider, model, effective_from). It's stored as NUMERIC(14,8) with the rate_card_id. Run-level totals are denormalized at run-end. Neither is recalculated on dashboard load.
Never in the data path
Agents call LLM and tool providers directly. Spineforge observes asynchronously via the OTel span pipeline. If Spineforge is unreachable, agents keep running — the FileSink absorbs events locally until the APISink recovers.
Dashboard
Six views. Every agent, every action.
The dashboard ships with Spineforge — not a separate product, not an add-on. Every registered agent is visible from day one.
Overview
System-wide health: total agents, actions, cost, and recent activity at a glance.
Agents list / detail
Every registered agent, its Spine ID, owner, lifecycle stage, and per-run history.
Cost & Usage
Cost breakdown by agent, model, and provider. Drill into any run to see the full action ledger.
Agent graph visualizer
Grid layout by default. Toggle to force-directed graph via d3-force to see agent relationships and delegation chains.
Lifecycle Kanban
Six-stage governance board: Development → Testing → Staging → Production → Degraded → Retired.
Per-agent timeline
Chronological event log for a single agent — every run, action, and credential lease in one view.
Supported today