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 what happens locally if your deployment can't check in. 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/enforcement overlay (so Studio can show a warning banner during the payment grace period 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. What actually disables a deployment is the local check-in behavior described in What happens if Studio can't check in: the deployment itself stops serving agent traffic when it cannot confirm a valid heartbeat.
Usage metering — durable, at-least-once delivery
Usage (model calls and their token counts) is metered per turn for billing — including the analysis coder's own model calls, which are reported as their own coder_analysis usage record so the work it does on the agent's behalf is accounted for. Billing is on prompt (input) tokens. 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; the customer is attributed by this license identity |
| Idempotency key | Ensures a retried event is counted only once |
| Execution identifier | Ties the event to the run that produced it |
| Usage kind | Which kind of usage the event records — for example a chat turn, a graph step, or a coder_analysis record for the coder's own model calls |
| Model usage | Which model role was used and its token counts (billing is on prompt/input tokens) |
| 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.
What happens if Studio can't check in
Studio needs to stay in contact with the Console to run. Each heartbeat confirms the deployment is licensed and in good standing, and agent execution depends on that confirmation succeeding.
If a heartbeat cannot be confirmed — because the deployment has lost outbound connectivity to the Console, or because there is an account or billing hold on your deployment — Studio disables agent execution and shows a banner asking you to contact your administrator. The banner stays on screen for as long as the deployment is disabled. Disabling covers all the ways agents run: chat, running a plan, and running a workflow now or on a schedule (re-enabling a paused schedule is blocked while the deployment is disabled). While disabled, the deployment returns an "unavailable" response on agent traffic; its diagnostic and re-activation endpoints stay reachable so an operator can confirm what is going on.
This is designed to be safe for you as the account owner:
- It is entirely local. Prometheus Research Labs never reaches into your AWS account to switch anything off — your deployment decides for itself based on what the signed heartbeat tells it.
- It is recoverable. Restore connectivity (or clear the account/billing hold) and the deployment resumes on its own after the next successful heartbeat — no redeploy needed. Usage that occurred while the Console was briefly unreachable is still delivered once contact is restored; nothing is lost.
- A billing suspension is temporary and clears automatically once the overdue invoice is paid. A revoked license is permanent — a revoked deployment cannot be reactivated, so you would create a new license key and redeploy.
If you see the banner, the two things worth checking first are outbound HTTPS connectivity from your deployment to the Console, and your account/subscription status in the Console. See FAQ and troubleshooting and Deployment troubleshooting.
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.