Licensing

Every agent runs against a signed license JWT. The license states who you are, what tier you're on, how many agents you can run, and when access expires. The agent verifies the signature locally before any work is dispatched — there is no "phone-home or die" latency between heartbeats.

What's in a license

The on-disk JWT carries the following claims. agentina status prints them at any time:

• plan — trial / standard / etc. Pinned by the activation token; cannot be upgraded in-place.
• max_agents — how many agents this license can be redeemed by. One activation token = one agent.
• features — capability flags (e.g. agent.coder, indexer). The control plane gates dispatch on these.
• update_channel — stable / beta / dev / enterprise-lts. Determines which release notes you see and which builds the auto-update hint surfaces.
• machine_binding — required / optional / none. With required the agent will refuse to start if the machine fingerprint drifts beyond the threshold.
• offline_grace_hours — how long the agent will keep running when the heartbeat is failing. Past the grace window, work refuses with GRACE_EXHAUSTED.
• exp — expiry. Past this point the license is dead; the EXPIRED sweeper also flips the server-side row.

Tiers at a glance

Numbers reflect the seeded defaults. Your actual license may differ — agentina status prints the truth.

Machine binding

When machine_binding=required, the agent computes a 5-component fingerprint (CPU, motherboard UUID, disk serial, MAC, hostname), hashes it, and binds the license to that hash at activation time. On every heartbeat it recomputes and scores the match against the bound hash.

• Score above threshold — everything continues normally.
• Score below threshold — the agent transitions to terminal fingerprint_mismatch and refuses further work.

To move an agent to new hardware: revoke the old activation in /portal/agents (or have an admin do it), mint a fresh activation token in /portal/tokens, and run agentina activate on the new box.

Suspension & revocation

Two paths can stop an agent from running:

Customer-level suspend

Set by an operator. The heartbeat response returns stop with reason customer_suspended; the agent transitions to terminal state within one heartbeat (~60 seconds). To unblock: contact support and they'll flip the customer record back to active.

License revocation

Set by an operator. Soft revocation by default: there's a 1-hour delay before it applies, and a 7-day window where the revocation can be restored. Reason codes the agent will see on heartbeat:

• EXPIRED — license exp passed. Set automatically by the EXPIRED sweeper.
• MANUAL_REVOKE — operator pulled the plug.
• PLAN_DOWNGRADE — new license issued; old one tombstoned.
• ABUSE / SECURITY_INCIDENT — investigation outcome.
• MACHINE_MISMATCH — fingerprint drift caught server-side (P2 feature).

Offline grace

If the heartbeat starts failing (network outage, control plane down, DNS hiccup), the agent enters degraded state and keeps doing whatever it was doing. After offline_grace_hours elapse without a successful heartbeat, it transitions to grace_expiredand refuses new work. A successful heartbeat at any point during the grace window snaps it back to active.

Grace counter is local to the agent. It does not survive a process restart that loses in-memory state — but on disk we persist the last successful heartbeat time, so a quick reboot doesn't cost you the whole grace window.