Architecture overview
AlphaAgent runs in three places: the AlphaAgent Console that Prometheus Research Labs operates, the AWS account you install AlphaAgent Organisations into, and one AWS account per AlphaAgent Studio deployment. This page shows which of those talk to each other, who opens each connection, and what crosses each boundary.
Who this is for
Security engineers, architects and CISOs reviewing AlphaAgent before or after an install. It assumes you know AWS accounts, IAM roles and CloudFormation.
Before you start
You do not need access to anything to read this page. To run the verification steps at the end you need read-only AWS access to your Organisations account and to at least one Studio account.
The three places
| Place | Who owns it | What runs there | Region |
|---|---|---|---|
| AlphaAgent Console | Prometheus Research Labs | Licence keys, the licence heartbeat and usage endpoints, the release catalogue and downloads, the Agent Store catalogue, billing through AWS Marketplace | A region we operate; see The Console side |
| Your Organisations account | You | The Organisations console and its engine: seven CloudFormation stacks, one ECS cluster, DynamoDB, S3, ECR, Secrets Manager, a Cognito user pool federated to your identity provider, an internal load balancer reached over your Transit Gateway | One of the eleven supported regions, chosen at install |
| Your Studio accounts (one per deployment) | You | Everything a deployment needs: five CloudFormation stacks in the deployment region, an internal load balancer and a Transit Gateway attachment to your network | The deployment region (a deployment created before private network access also has an edge stack in us-east-1 for its CloudFront front door) |
The eleven supported regions are us-east-1, us-east-2, us-west-2, eu-west-1, eu-west-2, eu-west-3, eu-central-1, eu-central-2, eu-north-1, eu-south-1 and eu-south-2. They are the regions that serve the US or EU Amazon Bedrock inference profiles Studio depends on.
What talks to what
Every connection below is opened from inside one of your accounts, or by your users' browsers. The Organisations console and the Studio deployments never call each other over the network: the engine manages each deployment through AWS APIs in its account, so nothing routes between their VPCs. Nothing operated by Prometheus Research Labs opens a connection into your accounts: the engine that deploys and updates Studio is the Organisations provisioner running in your own Organisations account.
| From | To | What | Who opens it |
|---|---|---|---|
| Your users' browsers | Organisations console | HTTPS over your Transit Gateway to the internal load balancer in your Organisations account, from your administrators' ranges; sign-in through Cognito federated to your identity provider (SAML) | The user |
| Your users' browsers and API callers | Studio | HTTPS over your Transit Gateway to the deployment's internal load balancer, from its user access ranges (an existing public deployment: through its CloudFront distribution); sign-in through the deployment's Cognito user pool federated to your identity provider (SAML) | The user |
| Organisations engine | Your Studio accounts | sts:AssumeRole into the role you created from the account template, with an External ID; then CloudFormation, ECR, Secrets Manager, ECS, DynamoDB and S3 calls in that account | Organisations, in your Organisations account |
| Organisations engine | Your Entra ID tenant | Microsoft Graph calls that create the Enterprise Application for a deployment and assign users to it | Organisations |
| Organisations engine | AlphaAgent Console | A signed credential check, the release catalogue, and the download of each release bundle | Organisations |
| Studio (agent-runtime) | AlphaAgent Console | Licence activation once, a licence heartbeat every 300 seconds, and usage events (token counts, never content) | Studio |
| Studio (agent-management) | AlphaAgent Console | Reads of the Agent Store catalogue over the same signed channel | Studio |
| Studio services | Amazon Bedrock | Model calls through the bedrock-runtime VPC endpoint in the deployment region, billed to your account | Studio |
| Studio connectors and sandboxes | Your data sources | Connector calls to your databases, warehouses, APIs and AWS resources; on your network only the internal service ranges and ports an administrator approved | Agent code you run |
| Studio web search service | The public web | Search queries and page fetches when an agent uses web search or browsing, through the NAT gateway or your firewall | Agent code you run |
| AlphaAgent Console | AWS Marketplace | An hourly usage report of billable prompt tokens against your Marketplace agreement | Prometheus Research Labs |
The exact fields on the Console channel are on What leaves your account. The cross-account role, statement by statement, is on What runs in your account (Organisations).
Steps: verify the picture in your own accounts
- In your Organisations account, list CloudFormation stacks. Seven stacks named
alphaagent-org-auth,alphaagent-org-data,alphaagent-org-jobs,alphaagent-org-release-cache,alphaagent-org-foundation,alphaagent-org-private-networkandalphaagent-org-appshould exist in the install region and nowhere else. - In a Studio account, list CloudFormation stacks in the deployment region. Five stacks named
alphaagent-<deployment id>-core,-stateless,-private-network,-computeand-taskdefshould exist. - In the same Studio account, find the account template's stack,
alphaagent-org-target-<account id>, in the account's first region (the Launch Stack link the Organisations console gives you opens there; an account registered earlier may have it in the Organisations region). - In VPC, open Transit gateway attachments in each account: one attachment of ours, tagged
alphaagent:deployment, to your Transit Gateway. On a deployment created before private network access,us-east-1holds instead one stack,alphaagent-<deployment id>-edge, with the Lambda@Edge function and nothing else. - Open the IAM role
AlphaAgentOrgTarget-prod(path/alphaagent-org/). Its trust policy should name exactly one principal, thealphaagent-org-task-rolerole in your Organisations account, with asts:ExternalIdcondition. - In IAM, confirm no role in the Studio account trusts any principal outside your own accounts.
What you should see
- Stacks only in the regions above. Any other region should carry nothing named
alphaagent. - One trust relationship into each Studio account, from your own Organisations account, guarded by an External ID.
- Outbound connections from Studio to
telemetry.api.alphaagent.prometheusrl.comon HTTPS. There is no inbound path from that host into your account.
Limits
- One region per Organisations install. A second region means a second install.
- New Studio deployments and new Organisations installs are private, reached only over your Transit Gateway; a deployment's network access is fixed for its life. Deployments created before private network access keep their CloudFront front door, whose edge half is in
us-east-1. - A private install uses no region besides its own, so a service control policy may deny
us-east-1; see Shared responsibility and best practices.
If something goes wrong
- A stack exists in a region you did not choose: confirm it belongs to a different install or a test, then raise it with us before deleting anything. Besides the stacks, AlphaAgent creates the account template's role, the Transit Gateway attachments and the resources listed on Everything AlphaAgent deploys.
- A trust policy names an account that is not yours: treat it as a security incident. The Organisations console prints the account id it expects when you add an account; compare the two.
- Studio shows the "Service halted" banner: the heartbeat to the Console is failing. Start with What leaves your account.