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: six CloudFormation stacks, one ECS cluster, DynamoDB, S3, ECR, Secrets Manager, a Cognito user pool federated to your identity provider | One of the eleven supported regions, chosen at install |
| Your Studio accounts (one per deployment) | You | Everything a deployment needs: four CloudFormation stacks in the deployment region plus one small edge stack in us-east-1 for the CloudFront front door | Deployment region plus us-east-1 |
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. 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 to the load balancer in your Organisations account; sign-in through Cognito federated to your identity provider (SAML) | The user |
| Your users' browsers | Studio | HTTPS to the CloudFront distribution in front of the deployment's load balancer; 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 sandboxes | Your data sources | Connector calls to your databases, warehouses, APIs and AWS resources | Agent code you run |
| Studio web search service | The public web | Search queries and page fetches when an agent uses web search or browsing | Agent code you run |
| Studio tasks at start | Docker Hub | Pulls of the Neo4j and SearXNG images named in the task definitions | ECS in your account |
| 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. Six stacks named
alphaagent-org-auth,alphaagent-org-data,alphaagent-org-jobs,alphaagent-org-release-cache,alphaagent-org-foundationandalphaagent-org-appshould exist in the install region and nowhere else. - In a Studio account, list CloudFormation stacks in the deployment region. Four stacks named
alphaagent-<deployment id>-core,-stateless,-computeand-taskdefshould exist. - In the same Studio account, switch to your Organisations install region: the account template's stack,
alphaagent-org-target-<account id>, is created there (the Launch Stack link the Organisations console gives you opens in that region). - Switch to
us-east-1and list stacks. One stack,alphaagent-<deployment id>-edge, should exist. It holds 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.
- The edge half of every Studio deployment is always
us-east-1, because CloudFront certificates and Lambda@Edge functions live there. A service control policy that deniesus-east-1blocks the front door; see Shared responsibility and best practices. - The CloudFront front door is always on for a Studio deployment; the Organisations console does not accept a deployment without it.
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. The account template's role is the only thing outside the six or five stacks that AlphaAgent creates.
- 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.