Licensing and telemetry
The license and usage channel is the one and only thing AlphaAgent sends out of your AWS account. This page documents that channel in full: what is transmitted, when, the exact fields each message carries, how delivery is made reliable, and the kill-switch behavior that enforces the license locally. If you are reviewing what data crosses your account boundary, this is the complete list — and it contains none of your business data. The administrator's view of creating and managing licenses is in License keys.
What crosses the boundary, and what does not
Three kinds of message flow from your Studio deployment to the AlphaAgent Console:
- Activation — once, when the deployment first comes online.
- Heartbeat — a small status message about every five minutes.
- Usage metering — counts of model usage, delivered as billable events.
None of these carry your prompts, your documents, your query results, your agent definitions, or your connector data. They carry license identity, deployment identity, health, and usage counts. The Console never connects into your account; all three messages are initiated by Studio, outbound only.
The channel is signed both ways
Every message on this channel is signed with a secret shared only between your deployment and the Console, and every response from the Console is signed too. This makes both directions tamper-evident: the Console can be sure a message genuinely came from your licensed deployment, and your deployment can be sure a response genuinely came from the Console and was not replayed. Each request also carries a one-time value and a timestamp, so a captured message cannot be replayed later.
The shared secret originates when your license is created. The Console reveals it exactly once, inside the license token you hand to your deployment; your deployment then stores it in its own Secrets Manager and uses it to sign from then on. The secret is never logged and never travels in any later message.
Activation
Activation happens once, automatically, when the deployment first starts with a valid license token (or on demand if an operator triggers it). Studio stores the license secret in your account's Secrets Manager and then tells the Console that this deployment is now live.
Fields transmitted on activation:
| Field | Meaning |
|---|---|
| License id | The public aalk_… identifier for your license (safe to log) |
| Host fingerprint | A hashed identifier for the deployment host — used to detect a license being reused on a different deployment, not to identify any person |
| Runtime version | The version of Studio that is running |
| Deployment kind | The kind of deployment (for example, an AWS deployment) |
The Console marks the license active, records the host fingerprint, runtime version, and deployment kind, and returns a signed confirmation. If the same license is later activated from a different host fingerprint, the Console rejects it — this is what prevents one license from being shared across multiple deployments. Re-activating from the same deployment (for example after a restart) is allowed.
Heartbeat
About every five minutes, Studio sends a signed heartbeat. Its purpose is to prove the deployment is still alive and licensed, and to receive any billing status the Console wants to surface.
Fields transmitted on a heartbeat:
| Field | Meaning |
|---|---|
| License id | The public identifier |
| Timestamp and one-time value | Freshness and replay protection |
| Runtime version | The running Studio version |
| Health summary | A short status of the deployment's own license health |
The Console records the heartbeat, resets its missed-heartbeat counter, and replies — signed — with whether the license is valid, a billing/delinquency overlay (so Studio can show banners before anything is enforced), and when it next expects to hear from the deployment.
On the Console side, missed heartbeats are tracked: a couple of misses move the license to a "warning" health state and more misses to "unhealthy." That tracking drives the health indicators an administrator sees in the Console; missed heartbeats alone do not disable anything — enforcement is the kill-switch below.
Usage metering — durable, at-least-once delivery
Usage (model calls and their token counts) is metered for billing. Because the Console must never be a single point of failure for your running deployment, metering is decoupled from delivery:
- As usage occurs, each billable event is written immediately to a durable queue (a DynamoDB table) in your own account. This write never blocks the agent and never loses data if the Console is temporarily unreachable.
- A background process drains that queue, sending each event to the Console over the signed channel, and retries with backoff on transient failures. Events that are confirmed delivered are marked done; events that are permanently stale (their billing period already closed) are dropped.
- If the deployment restarts mid-delivery, any in-flight events are returned to the queue and retried.
Each usage event carries an idempotency key (alongside an execution identifier), and the Console deduplicates on it. This makes delivery at-least-once on the wire but exactly-once in effect: retries cannot double-count usage.
Fields transmitted per usage event:
| Field | Meaning |
|---|---|
| License id | The public identifier |
| Idempotency key | Ensures a retried event is counted only once |
| Execution identifier | Ties the event to the run that produced it |
| Model usage | Which model role was used and its token counts |
| Billing period | The period the event belongs to |
The Console folds these into hourly aggregates for billing. None of these fields contain prompt content, output content, or any of your data — only counts and identifiers.
The kill-switch state machine
AlphaAgent enforces its license with a local kill-switch inside your deployment, not a remote off-switch. Studio continuously evaluates how long it has been since its last successful, verified heartbeat and moves through four states:
- OK is normal operation.
- WARN and UNHEALTHY are reached as successful heartbeats lapse; the deployment keeps working and shows status to operators.
- KILLED is reached one of two ways: a long outage where the deployment cannot reach the Console for about 24 hours (time-based decay), or an immediate trip when the Console responds that the license is revoked or fails authentication (force-kill).
While KILLED, the deployment refuses agent traffic — returning HTTP 451 (Unavailable For Legal Reasons) — except for the diagnostic and re-activation endpoints, which stay open so an operator can check status and re-activate without rebuilding anything. A successful re-activation and heartbeat returns the deployment to OK.
Two things make this safe for you as the account owner: it is entirely local (PrometheusRL never reaches into your account to disable anything), and "frozen for non-payment" is kept distinct from "killed for revocation" — a billing delinquency surfaces as banners and stops new usage being accepted for billing, but it is the heartbeat validity, not delinquency alone, that drives the kill-switch.
Where to go next
- Data residency and security — how this channel fits the overall "everything stays in your account" guarantee.
- License keys — creating, monitoring, and revoking licenses from the Console.
- What runs in your account — the resources this telemetry reports on.