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.
Deploy your first Studio
For the DeploymentOperator (or owner or operator), with whoever manages your network and private DNS. Before you start: a verified account whose role allows the deployment's region, a connected Entra tenant, the licence token, an Issued ACM certificate for the Studio hostname in the deployment's region, Bedrock model access checked there (Register an AWS account), the Transit Gateway, ranges and firewall decisions from Private network access, and a sizing tier from Infrastructure sizing and costs if not the default.
1. Decide: standard or governed
The wizard's Ownership field is the one choice you cannot change later ("This cannot be changed later."): a governed deployment is a standard Studio whose resources are shared.
| Standard · personal resources | Governed · shared resources | |
|---|---|---|
| Sees, edits, runs, shares or deletes an agent, workflow, connector, environment or knowledge graph | Its creator | Everyone assigned |
| Workspace files you can open | Your own | Every user's; you still write only into your own folder |
| Sees and stops a run | Whoever started it | Everyone assigned |
| Attribution | Unchanged | Unchanged |
| Programmatic access (API keys) | Not available | The only kind a key can be bound to |
| PII redaction default | Off | Mask, preselected |
| Per-user caps (256 workflows, 256 agents) | Your own | Your own; not pooled |
Choose Standard when people build for themselves; Governed when a team maintains one set together, another system must start workflows through the API, or you want Mask as the floor. Work moves between kinds through a library (Libraries and sharing). Programmatic Access disables New API key with "Create a governed deployment first" until one exists.
2. Fill in the wizard
Open Fleet and click New deployment (disabled: "Requires the DeploymentOperator role (or owner/operator)"). The wizard is one page, saved to a draft 400 ms after you stop typing (the draft id is in the URL); re-read the text fields in Review and launch.
| Section | What to enter |
|---|---|
| Start from a template (optional) | A saved Fleet Configuration Template pre-fills fields; Start blank for a first deployment. |
| Target account | Deployment name (up to 200 characters; shown in Fleet and the header with the domain beneath; typed to confirm destructive actions). Account: only verified accounts; it sets Region and the Bedrock inference zone. |
| Release version | Version ("Versions from the AlphaAgent catalogue. A version is mirrored into your organisation the first time a job uses it."): only the latest stable Studio release is offered, and an older one is refused with the latest named (which release you can choose); the first job on a version copies it during Preflight. Private network access needs Studio 2.0.15 or later, and the Claude 5.5 models need 2.0.20 or later, so launch refuses any release before 2.0.20 (Supported models). |
| Parameters | Ownership (section 1), the nine fields in the next table, then the Models, Network access, Outbound internet traffic and Trusted certificate authorities sections below it. |
| Licence | Paste the License Token (aalk_<id>.<secret>, not the License ID) and click Provide licence. It goes once to your organisation's secret store; the section then reads Licence provided with aalk_<id>.***. Replace the licence token changes it. |
| Identity provider | The connected tenant, "<tenant name> (Microsoft Entra ID)"; no "none" option. |
The Parameters fields, one per row:
| Field | Enter | Default | Changeable later |
|---|---|---|---|
| Ownership | Standard or Governed (section 1) | none | No |
| Environment | dev, staging or prod; part of every AWS resource name | none | No |
| Cognito domain prefix | Auto-generated | generated | No |
| Studio app domain | Paste studio.example.com; stored lower case | none | Not from the console |
| ACM certificate ARN (this region) | Pick from the Issued certificates or paste the ARN | none | Not from the console |
| Bedrock inference zone | us or eu | from the region | No |
| Fargate sizing profile | xs, small, standard, large, xlarge | Default: standard, the first option | Fleet Configuration Template and Update Manager |
| ElastiCache node type | cache.t4g.medium, cache.m7g.large, cache.r7g.large, cache.r7g.xlarge | Default: cache.t4g.medium, the first option | Fleet Configuration Template and Update Manager |
| Run data retention (days) | 1 to 3650 | blank, 90 | Yes, from Overview |
| PII redaction default | Off, Mask or Hash; a workflow or run can tighten (Off → Mask → Hash), never loosen | Off; Mask preselected on a governed deployment | Fleet Configuration Template and Update Manager |
The Models section has one picker per model class, each with what the class runs beneath it and pre-selected to the default (Supported models):
| Picker | Offers | Default | Changeable later |
|---|---|---|---|
| Coordinator model (most capable) | Claude Opus 5.5 · anthropic.claude-opus-5-5 | "Default: Claude Opus 5.5 · anthropic.claude-opus-5-5" | Fleet Configuration Template and Update Manager |
| Worker model | Claude Sonnet 5.5 · anthropic.claude-sonnet-5-5 | "Default: Claude Sonnet 5.5 · anthropic.claude-sonnet-5-5" | Fleet Configuration Template and Update Manager |
| Chat-title model (fastest, lowest cost) | Claude Haiku 5.5 · anthropic.claude-haiku-5-5 | "Default: Claude Haiku 5.5 · anthropic.claude-haiku-5-5" | Fleet Configuration Template and Update Manager |
A draft that names a model its class does not take, such as a Claude 4.x id saved before, shows "The Coordinator model must be anthropic.claude-opus-5-5." (or the Worker or Chat-title model) under the picker until you choose again.
The network sections, set once when the deployment is created except where the last column says otherwise:
| Field | Enter | Changeable later |
|---|---|---|
| Network access | Always Private (over your Transit Gateway): "This deployment's load balancer is internal, with no CloudFront. Users reach it over your Transit Gateway from the user access ranges." | No |
| VPC range | A private range unique on your routed network, from /16 to /24 with your Transit Gateway or /16 to /23 with the NAT gateway. The helper reads "A /24 is enough for one Studio with egress through your Transit Gateway." (or "A /23 is enough for one Studio with AlphaAgent's NAT gateway.") and the subnets it will hold. No default | No |
| Transit Gateway ID | tgw-... in this region, owned by the account or shared with it through AWS Resource Access Manager | No |
| User access ranges | "Ranges your users and API callers connect from, comma separated. Only these ranges are routed to Studio." Up to 10 | Yes, from Overview |
| Internal service ranges | "Ranges of internal APIs and databases that connectors and agent code may reach, comma separated." 1 to 10 | Yes, from Overview |
| Internal service ports | Optional: up to 5 extra ports agent code may use on those ranges, for example 5432, 3306. "Port 443 is always allowed." | Yes, from Overview |
| Outbound internet traffic | Through AlphaAgent's NAT gateway or Through your Transit Gateway (your firewall); no default | No |
| Your firewall's public egress IP addresses | Only with your Transit Gateway: 1 to 8 public IPv4 addresses, comma separated | No |
| Trusted certificate authorities | Optional: paste or Upload PEM file with your root CA, the issuing CA that signed your services' certificates, or both; up to 20 certificates, 64 KB in total. Each one is listed with its subject, issuer, expiry and SHA-256 fingerprint | Yes, from Overview |
A value that breaks a rule is refused under its field with the reason (Private network access). The VPC range is also checked against every other deployment of your Organisation and the Organisation's own range, and the live preflight checks it against the VPCs already in the account.
3. Review, preflight, launch
Review and launch lists Deployment, Account and region, Release, Licence, Payload (Studio), Ownership, Deployment size, Redis node type, Coordinator model, Worker model, Chat-title model, Run data retention, PII redaction default, Network access, VPC range, Subnets, Transit Gateway, User access ranges, Internal service ranges, Internal service ports, Outbound internet traffic (and Firewall egress IP addresses) and Trusted certificate authorities. Click Run preflight; while disabled its hover text names the incomplete section ("Parameters: Studio app domain is not set yet."). Results are Passed, Failed, Warning or Skipped, including The Transit Gateway is visible in this account and region, the VPC range checks, The selected models can be invoked in this account and region and Bedrock quotas for the selected models meet the recommended floors (what each refuses or warns about: Supported models). "Cannot launch: <checks>." blocks; a warnings line lists the checks to review before launching and does not block. Save as template (optional; a Name up to 100 characters; captures release and parameters, not account, region, prefix or certificate). Launch Deployment opens the progress screen with no confirmation dialog; Cancel deletes the draft, also without one.
4. Watch the install job
Expect 45 to 50 minutes (measured: 48 and 46 minutes on xs). The Jobs view shows N of M steps complete and the Provisioning steps table (#, Step, Status, Elapsed / duration); click a step for its detail, Attempt N and the log tail (Copy, Download full log). The stream reconnects if it drops and may run 30 seconds behind.
| # | Step | Does | Measured |
|---|---|---|---|
| 1 | Preflight | Readiness checks, the VPC range, the Transit Gateway, and the selected models' access and Bedrock quotas; caches bundle and images | 5 to 7 min |
| 2 | Core stack | Network, data stores, buckets, user pool | 7 to 8 min |
| 3 | Neo4j credentials | Graph database secret | seconds |
| 4 | Push Studio + env images | Images into your account | under 1 min |
| 5 | Verify the images landed in the target account | Digest check | seconds |
| 6 | Seed configuration secrets | The three model ids and their effort settings, ownership, redaction, retention, the internal service ranges | seconds |
| 7 | Re-seed trusted certificate authorities | Your CA certificates, if any | seconds |
| 8 | Upload the Studio SPA | The web app | seconds |
| 9 | Edge stack (not used by Private deployments) | Skipped | none |
| 10 | Stateless stack (ALB) | The internal load balancer | about 5 min |
| 11 | Private network (Transit Gateway attachment and routes) | Requests the attachment and waits for your team to accept it, then adds the routes, load balancer access and sandbox ports (and with your Transit Gateway the default route and endpoints) | about a minute after acceptance |
| 12 | Compute stack (ECS cluster) | Cluster, roles | about 1 min |
| 13 | Task-def stack (services) | Services at your sizing tier | about 18 min, the long pole |
| 14 | Wait for services + connectivity heal | With your Transit Gateway, first the outbound traffic check; then every service running and reachable | about 6 min |
| 15 | SAML SSO (required) | Enterprise Application in your tenant | seconds |
| 16 | Verify configuration | The deployment's own checks | seconds |
At step 11 the job reads Waiting for you with the card Accept the Transit Gateway attachment, naming the attachment, the Transit Gateway, its owner account and the deployment's VPC. Once your network team has accepted it, choose I have accepted it; the job carries on (Private network access). In an account that has never run ECS, step 12 may wait a few minutes for AWS to prepare ECS's service-linked role, and retries its cluster once by itself.
A second deployment launched while the first loads images waits at Preflight: "another job is already loading the images of release stable/<version>; waiting for it rather than doing the work twice". Step statuses: Pending, Running, Waiting for you, Succeeded, Failed, Skipped; parked and failed steps: Troubleshooting the install.
5. Create the DNS record
Overview > Network shows Network access "Private · internal load balancer", the VPC (its ID and range) and Subnets; Endpoints shows App domain, DNS target (until it exists: "appears once the Stateless step has finished") and Load balancer. The Overview re-reads itself every 15 seconds while the job runs. In the private hosted zone your users resolve, create one record pointing at the internal load balancer, and associate that zone with the deployment's VPC (or add the equivalent resolver rules):
CNAME <Studio app domain> -> <DNS target value, internal-...elb.amazonaws.com>
What you should see
The header shows the deployment name with the app domain beneath, Status Healthy and Version (reload after the job ends). Network reads Attachment "Available" and Network check healthy; Jobs lists the install job Succeeded. From a user access range, https://<Studio app domain> shows the Studio sign-in page; nobody can sign in until After the deploy.
Notes
- Fixed for life: Environment, Cognito domain prefix, Ownership, region, Network access, VPC range, Transit Gateway ID and Outbound internet traffic; the tables above say how the other fields change.
- Wrong kind chosen: create another deployment and delete the first (Deleting a deployment).
- New deployments are private; there is no CloudFront option. Deployments created before private network access keep their CloudFront front door through every update. One draft launches one deployment. A model left blank in a draft launches as its default, which the deployment records; a blank sizing or Redis value reads as its default in Review and on the Overview.
- Fleet Configuration Templates carry no network settings, so a template applies to private and existing public deployments alike.
?minimal=1on the wizard URL deploys "A minimal test deployment, not Studio itself" in about two minutes, without domain, certificate, prefix or models, to prove the account can take a deployment.