Install AlphaAgent Organisations into a new, empty AWS account, and give every AlphaAgent Studio deployment a new, empty AWS account of its own. Three reasons:
- It is AWS best practice to isolate each workload in its own account, with its own limits, billing view and permissions.
- Amazon Bedrock quotas are set per AWS account. Many users in one deployment share one quota and exhaust it; one account per deployment keeps each team's capacity its own.
- The blast radius is smaller. A problem in one deployment, or one team's mistake, cannot reach the others.
Private network access
For the network and cloud engineers who prepare a customer network for AlphaAgent: every new Organisations install and every new Studio deployment is private, and this page lists what your side provides before the installer and the deploy wizard ask for it.
Architecture
A private install takes one of two designs, chosen under Outbound internet traffic for the Organisations install and for each Studio deployment. Each is a two-page PDF: the diagram, then how traffic flows and what each side provides.
- Through your Transit Gateway (your firewall). The AlphaAgent VPCs have no NAT gateway, internet gateway or public subnet, and all outbound internet traffic goes over your Transit Gateway to your own egress or inspection VPC and firewall.
- Through AlphaAgent's NAT gateway. Outbound internet traffic leaves from a NAT gateway in the AlphaAgent VPC, while your users and API callers still reach the internal load balancers only over your Transit Gateway.
Download the architecture with outbound traffic through your firewall (PDF)
Download the architecture with outbound traffic through AlphaAgent's NAT gateway (PDF)
How a private install is reached
The Organisations console and each Studio deployment run behind an internal Application Load Balancer in their VPC's private subnets, with no CloudFront and no internet-facing listener. Your users and API callers reach them over your AWS Transit Gateway, from ranges you list. Agents reach your internal APIs and databases over the same attachment, only in the ranges and on the ports you approve. Outbound internet traffic leaves either through a NAT gateway in the AlphaAgent VPC or through your Transit Gateway and your own firewall.
The Organisations console never calls a Studio deployment over the network: it manages each one through AWS APIs in that deployment's account. Nothing needs a route between the Organisations VPC and a Studio VPC.
What to have ready
| Item | Organisations | Each Studio deployment |
|---|---|---|
| AWS account and region | A fresh account; one of the supported regions | A fresh account per deployment, registered in Organisations with the deployment's region first in its allowed regions (Register an AWS account) |
| Transit Gateway | In the install region, owned by the account or shared with it through AWS Resource Access Manager, with the share accepted | The same, in the deployment's region |
| Someone to accept the attachment | Your network team, in the account that owns the Transit Gateway, unless it accepts attachments automatically | The same, once per deployment |
| VPC range | A private range, unique on your routed network (below) | A private range per deployment, unique on your routed network |
| User access ranges | Up to 10 ranges your administrators connect from | Up to 10 ranges your users and API callers connect from |
| Internal service ranges | Not used | 1 to 10 ranges of internal APIs and databases that connectors and agent code may reach |
| Internal service ports | Not used | Up to 5 extra ports agent code may use to reach the internal service ranges, for example 5432 and 3306; port 443 is always allowed |
| Outbound internet traffic | Through AlphaAgent's NAT gateway, or through your Transit Gateway and your firewall | The same choice, per deployment |
| Firewall egress IP addresses | With your firewall: its public egress addresses, 1 to 8 | The same, per deployment |
| Hostname and certificate | A hostname you control and an Issued ACM certificate for it in the install region | An app hostname and an Issued ACM certificate in the deployment's region |
| Private DNS | A record for the hostname in a private hosted zone (or resolver rules) your administrators resolve | A record for the app hostname in a private zone your users resolve |
| Your own certificate authorities | Not used: the console never calls your internal services | Optional: the CA certificates of internal services agents call |
Network access, the VPC range, the Transit Gateway and the outbound traffic choice are set when an install or deployment is created and cannot be changed later. A Studio deployment's user access ranges, internal service ranges, ports and certificate authorities can be changed afterwards from its Overview.
Choose the ranges
Private deployments are routed on your network, so every range must be unique across your routed address plan.
- VPC range. Inside 10.0.0.0/8, 172.16.0.0/12 or 192.168.0.0/16. With outbound traffic through your Transit Gateway it may be a /16 to a /24, and a /24 is enough; it is split into two private subnets. With the NAT gateway it may be a /16 to a /23, and a /23 is enough; its first half holds the two private subnets and two /28 subnets at the start of the third quarter hold the NAT gateway. There is no default. It must not overlap any VPC already in the account, any other deployment's range in your Organisation (the Address plan lists them), the Organisation's own range, or your lists.
- User access ranges and internal service ranges. IPv4 ranges inside 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 or 100.64.0.0/10, written as CIDRs and separated by commas; a single address is read as a /32. No entry may overlap the VPC range or another entry in either list.
- Ports. Numbers from 1 to 65535, never 443, and only with at least one internal service range.
The wizard and the installer refuse a value that breaks a rule and say which, for example "10.0.0.0/8 overlaps this deployment's VPC range 10.61.0.0/24." or "Port 443 is always allowed. Leave it out."
The Transit Gateway attachment
- The install (or the deployment's job) requests an attachment of the VPC's two private subnets to your Transit Gateway, through the EC2 API, tagged with the deployment.
- If your Transit Gateway does not accept attachments automatically, the job waits. In the Organisations console the deployment's job shows Accept the Transit Gateway attachment: "Waiting for you: accept the Transit Gateway attachment
<attachment id>in the account that owns<Transit Gateway id>(<owner account>). It connects this deployment's VPC<vpc id>in<account>,<region>. Then choose I have accepted it." The installer prints the same for the console's own VPC and waits for Enter; with--yesit checks every 30 seconds for up to an hour. - Your network team accepts the request in the account that owns the Transit Gateway. Match on the attachment ID, the VPC ID and the account ID: the owner's view does not show the requester's tags. Measured: an accepted attachment became available 75 to 100 seconds later.
- Choose I have accepted it (or press Enter in the installer). The job adds AlphaAgent's routes and load balancer rules and carries on. A request nobody answers expires after seven days; Stop the install withdraws it.
- In your Transit Gateway route tables, associate the attachment and route back to it: propagate the VPC range (or add a static route for it) into the route tables used by your user access ranges and your internal service ranges. With outbound traffic through your Transit Gateway, the attachment's route table also sends 0.0.0.0/0 to your egress or inspection VPC, and that path routes replies back to the VPC range.
If the attachment is rejected or deleted later, the job fails with tgw_attachment_rejected or tgw_attachment_deleted, and Resume (or Apply again on the Overview of an installed deployment) requests a new one for your team to accept. Troubleshooting the install lists every case.
The routes AlphaAgent adds in its VPC
In the private route table of each AlphaAgent VPC:
- one route per user access range and per internal service range, to your Transit Gateway;
- with outbound traffic through your Transit Gateway, a default route (0.0.0.0/0) to it;
- with outbound traffic through your Transit Gateway, a route that drops every other address in 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 and 100.64.0.0/10 inside the VPC, so a private range you did not list is never sent to your network.
The load balancer accepts HTTPS (and HTTP, which redirects) only from the VPC range and the user access ranges. Agent code in a sandbox reaches the internal service ranges on port 443 and on the approved ports, and nothing else on your network. Connectors and the web browsing tool refuse a private address outside the internal service ranges, and always refuse the deployment's own VPC range, loopback and the instance metadata addresses, whatever the lists say (Data connectors).
Private DNS
After the load balancer exists, the console (or the installer) shows two things your DNS team needs:
- The DNS target: the internal load balancer's DNS name. Create a CNAME (or a Route 53 alias record) for the hostname in the private hosted zone your users resolve. The Overview shows it as DNS target once the Stateless step has finished; the installer prints it after its
appstep ("Point<hostname>at<load balancer>in the private DNS zone your administrators resolve, and associate that zone with VPC<vpc id>."). - The VPC ID. Associate that private hosted zone with the AlphaAgent VPC, or add the equivalent Route 53 Resolver rules, so names resolve inside the VPC too. For a zone in another account, authorise the association in the zone's account, then associate the zone from the AlphaAgent account.
The association belongs to your zone's account. Before you delete a deployment or tear down Organisations, disassociate your zone from its VPC. After the VPC is gone, only the zone's account can see or remove the stale association: remove it from the zone. AlphaAgent never changes your DNS.
Outbound internet traffic
Through AlphaAgent's NAT gateway. The VPC keeps a NAT gateway, an internet gateway and two small public subnets that hold nothing else. Outbound traffic leaves from the NAT gateway's Elastic IP address, which is the address external services see.
Through your Transit Gateway (your firewall). The VPC has no internet gateway, no NAT gateway, no Elastic IP and no public subnet. AlphaAgent adds the default route to your Transit Gateway, and interface endpoints so that calls to AWS services in the deployment's own region stay on AWS: for Studio, AWS Lambda, Amazon EventBridge, Amazon SNS, Amazon CloudWatch, Amazon Bedrock and the Session Manager messages endpoint, beside the endpoints every deployment has (Amazon S3, DynamoDB, Secrets Manager, STS, ECR, CloudWatch Logs, SQS, Systems Manager and the Bedrock runtime); for Organisations, the AWS services its engine calls in its region, Amazon Bedrock and Service Quotas among them. You give your firewall's public egress addresses: they are shown on the Overview, and the first one is the Deployment egress IP that the Snowflake connector's network policy uses.
The firewall allow-list
From the VPC range, allow outbound HTTPS (443) to these hosts, with no TLS inspection. <region> is the deployment's or the Organisation's region.
| Host | For | Studio | Organisations |
|---|---|---|---|
telemetry.api.alphaagent.prometheusrl.com | Licensing, the Organisation credential and the release catalogue | Required | Required |
<prefix>.auth.<region>.amazoncognito.com | The sign-in domain: the internal load balancer calls it whenever anyone signs in. The prefix is the deployment's Cognito domain prefix (or the console's sign-in prefix) | Required | Required |
cognito-idp.<region>.amazonaws.com, and the same host for every region you deploy Studio into | The user pools of the Organisation and of each Studio. There is deliberately no interface endpoint for it: Cognito does not accept private connections to a user pool that has a sign-in domain | Not needed | Required |
iam.amazonaws.com, cloudfront.amazonaws.com | AWS global services with no regional endpoint: name checks when Studio is installed, Verify and Clear account | Not needed | Required |
prl-alphaagent-artifacts-prod.s3.amazonaws.com, prl-alphaagent-artifacts-prod.s3.eu-west-2.amazonaws.com | Release downloads; allow both names | Not needed | Required |
login.microsoftonline.com, graph.microsoft.com | Microsoft Entra ID, once you connect it | Not needed | Optional |
aadcdn.msauth.net, login.live.com, eu-mobile.events.data.microsoft.com | The Microsoft sign-in page, which loads these too for users behind a proxy | Not needed | Optional |
www.google.com, cse.google.com, html.duckduckgo.com, search.brave.com | Agents' web search. Each one you allow adds its results; with none, web search returns no results | Optional | Not needed |
| The regional AWS endpoints listed below, for a Studio in a region other than the Organisation's | Managing a Studio deployment in another region: installs, updates, preflight and Verify. Allow each host, or a regional wildcard such as .<region>.amazonaws.com. Verify and Clear account also look in us-east-1 while a registered account allows it | Not needed | Required when it applies |
Regional endpoints for a Studio in another region
A Studio in a region other than the Organisation's needs these endpoints in its region through the firewall, or a regional wildcard such as .<region>.amazonaws.com. Each host has the form <service>.<region>.amazonaws.com, with <region> the Studio's region:
sts,dynamodb,cloudformation,ecs,ec2ecrasapi.ecranddkr.ecr(the registry's API and Docker hosts)secretsmanager,s3,servicequotas,cognito-idp,acmmonitoring,bedrock,logs,lambda,elasticloadbalancing,elasticache
In the Organisation's own region, most of these have interface endpoints and need no firewall entry.
Web pages agents open with the browsing tool, and public services your connectors call, are reached only if your firewall allows them. A Studio deployment in another region than the Organisation reaches that region's AWS endpoints through your firewall too, so keep Studio deployments in the Organisation's region where you can.
Two rules apply to every host you allow:
- No TLS inspection on the licence host and the sign-in domain. AlphaAgent checks that their certificates come from a public certificate authority, and a firewall that replaces them stops the job with
egress_tls_intercepted. Web search checks public certificates as well, so inspection breaks it too. - Match the reassembled TLS server name. Agent code, web search and the browsing tool use current TLS clients whose ClientHello spans more than one TCP segment. Your firewall must match the server name (TLS SNI) after reassembling the ClientHello, not on the first segment; otherwise allow-listed hosts pass a short check and then reset in chat. On AWS Network Firewall, use the application-layer default actions (
aws:drop_established_app_layeroraws:alert_established_app_layer) and gate reject rules on the parsed server name.
The check every job runs
With outbound traffic through your Transit Gateway, every install, upgrade and reconfiguration first runs one short task in the VPC's private subnets. It connects to each required host with a small and a full-size ClientHello, checks each certificate's issuer, and confirms that the AWS endpoints resolve inside the VPC. The job stops before any service starts and names the host:
| Code | Meaning | Fix on your side |
|---|---|---|
egress_unreachable | A required host is not reachable from the AlphaAgent subnets | Route 0.0.0.0/0 for this attachment to your egress path and allow the host on port 443, then resume |
egress_tls_intercepted | Your firewall replaces the host's certificate | Exempt the host from TLS inspection, then resume |
egress_tls_split_hello_reset | A full-size ClientHello is reset while a small one gets through | Match the server name after reassembling the ClientHello, then resume |
egress_endpoint_missing | An AWS endpoint does not resolve inside the VPC | Resume; if it fails again, share the diagnostic ID with your AlphaAgent contact |
The installer runs the same check in its settle and doctor steps for the Organisations VPC, failing on a required host and warning on an optional one.
Your own certificate authorities
Internal services whose certificates come from your own (private or corporate) certificate authority are trusted once you add the CA certificates to the deployment, in the wizard's Trusted certificate authorities section or later from the Overview. Agents then trust them, in addition to the public certificate authorities, for REST and MCP connectors, SQL connectors with verify-ca or verify-full, agent code and web browsing; never for licensing, AWS or sign-in. Deployment detail describes the field and its limits.
us-east-1
A private install never uses us-east-1: there is no CloudFront front door and no us-east-1 certificate. Register Studio accounts with AllowedRegions naming only the regions you use, the deployment's region first. Only accounts that also hold a public deployment created before private network access need us-east-1 for its front door.
What you should see
- In the Organisations console, the deployment's Overview reads Network access "Private · internal load balancer", with its VPC, Subnets, Outbound internet traffic, Transit Gateway, Attachment "Available" and Network check rows, and the internal load balancer as DNS target.
- From a user access range, the hostname resolves to private addresses and opens the sign-in page; from anywhere else it neither resolves nor answers.