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.
Install Organisations
For the cloud engineer with AWS credentials for the fresh Organisations account and Python on a workstation; the Console administrator generates the credential. Before you start: everything on Before you start. The SAML metadata (step 10) can be prepared while the early steps run.
1. Get the credential and the bundle
- In the AlphaAgent Console, open Organisation. On the credential card click Generate credential, then in Credential created click Copy token and store the value: it is shown once, and the installer keeps it in AWS Secrets Manager in your account. Viewers cannot generate, rotate or revoke.
- Under Organisation bundle the newest row is labelled "latest"; older rows read "Superseded" and cannot be downloaded. Click Download bundle (the link is short-lived). The file is
alphaagent-org-cfn-bundle-<version>.zipwith dashes for dots, for examplealphaagent-org-cfn-bundle-1-0-16.zip. - Unzip into a fresh, empty directory and keep the layout:
orgctl.pyimports the modules beside it and writes its progress file here. ReadREADME.mdandRELEASE.txt; the templates undercloudformation/are there for your review (Everything AlphaAgent deploys). No checksum is published; thebundle-completecheck catches a short download.
2. Start the installer and answer the questions
With AWS credentials set in the shell (AWS_PROFILE, or AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY), run:
python3 orgctl.py
The banner "AlphaAgent Organisations installer" reports "No install recorded on this machine." (or "An install is already under way here: N/12 steps done.") and asks Start the install now?; Yes equals python3 orgctl.py install. Every question shows its default in brackets; Enter accepts it; answers are remembered.
| Question | Answer | Default |
|---|---|---|
| "AWS region to install AlphaAgent Organisations into" (a menu) | The region your certificate was issued in; skipped with --region or AWS_REGION. | none |
| "Is this the correct AWS account and region?" (after AWS account, Identity, Region) | Check the id is the fresh Organisations account; No prints "Stopped; nothing was changed." | Yes |
| "How do you want to proceed?" | Only when an Organisation or checkpoints already exist: the Resume menu (Troubleshooting the install). | Resume |
| "Environment": prod, staging or dev | Part of every resource name. | prod |
| "Hostname your team will use for the Organisations console" | Hostname only, lower case, no scheme (org.example.com). | required |
"ARN of the ACM certificate for that hostname, issued in <region>" | Enter: the installer prints "Found an issued certificate covering <host>" and offers the match (or lists several). | the match |
| "Private network range (/16) for the Organisation VPC" | A private IPv4 /16; four /20 subnets (two public, two private) are carved from it. | 10.70.0.0/16 |
| "Email address for the Organisation's first owner and break-glass administrator" | Your own address, spelt as your identity provider sends it; it gets the owner role and is the only sign-in left if single sign-on breaks. | required |
| "Proceed?" after the Summary | Check it: account, Identity, Region, Environment, Console URL, Certificate, Sign-in domain <prefix>.auth.<region>.amazoncognito.com, VPC and subnets, Break-glass admin, Console endpoint, the six stacks alphaagent-org-auth, -data, -jobs, -release-cache, -foundation, -app. | Yes |
The sign-in prefix is derived, not asked: alphaagent-<account id>-<region> (preset only through --config). "Release tag to push" and "AlphaAgent Console base URL" are asked only when RELEASE.txt lacks them, never with a downloaded bundle; two more questions arrive inside steps 9 and 10.
3. The twelve steps
Each step prints "Step N/12 - <label>", is checkpointed when it finishes, and prints "already done, skipping" on a later run. Stack creation streams CloudFormation events to the terminal.
1/12 Preflight checks. Runs the fifteen checks from Before you start and prints a table (STATUS, CHECK, WHAT IT VERIFIES), a -> remediation under each non-passing row, then "N passed, N warning(s), N failed, N skipped". WARN continues; any FAIL stops with "Nothing has been created, so this is free to repeat." Records the confirmed account and region.
2/12 Auth stack (Cognito) + print the SAML SP values. Creates alphaagent-org-auth (the user pool, its sign-in domain, the load balancer's app client), then prints the box FOR YOUR IDENTITY ADMINISTRATOR with the Identifier, Reply URL, Sign-on URL, provider name and three required claims, also written to org-saml-sp-values.txt. Hand it over now: Sign in with Entra ID.
3/12 Foundation and data stacks. Creates alphaagent-org-data, alphaagent-org-jobs and alphaagent-org-release-cache concurrently, then alphaagent-org-foundation: the VPC with four subnets, NAT, VPC endpoints, security groups, S3 buckets, the ECR repository, six empty Secrets Manager secrets and log groups. Allow 15 to 20 minutes (the installer's own estimate).
4/12 Push the Organisation image to your registry. Pushes image.tar.gz as alphaagent-org:<version> into the repository with crane, regctl or Docker, printing "image transport: <tool>", "authenticated to <registry>" and the digest, or "already in <repo> ... - skipping".
5/12 Write the application's configuration secrets. Fills the configuration secrets; mints the service signing key and the internal API key once and preserves them on every later run ("minted", "preserved (unchanged)", "updated (N keys)"). The console credential secret is left to step 9.
6/12 Upload the Organisations console. Uploads the spa/ files to the console bucket and confirms its CORS rule allows https://<hostname>.
7/12 App stack (ALB, cluster, services). Creates alphaagent-org-app: the internet-facing Application Load Balancer with Cognito authentication, the ECS cluster with the org-api and org-provisioner services, the console-serving Lambda; stages org-target-account-role.yaml for the Accounts screen. Ends by printing Console hostname and Load balancer: create the CNAME (or Route 53 alias) from the hostname to the load balancer now.
Console hostname: org.example.com
Load balancer: alphaagent-org-<id>.<region>.elb.amazonaws.com
Point the hostname at the load balancer with a DNS CNAME (or a Route 53 alias record) if you have not already.
8/12 Wait for services to reach steady state. Waits up to 900 seconds for org-api and org-provisioner (status every 15 seconds), checks the two target groups, then requests https://<hostname>/ and /accounts expecting "302 to the Cognito hosted UI". Before DNS resolves it warns "could not reach ... that is expected." and continues; re-run python3 orgctl.py settle once it does.
9/12 Register this Organisation with AlphaAgent Console. Asks "Organisation machine credential for AlphaAgent Console": paste the credential from step 1 (not echoed). It is checked against the Console endpoint in RELEASE.txt and stored in the alphaagent-org-console-credential secret; done reads "Console accepted the credential (HTTP 200)". Skipped with "already holds a credential; re-validating it" when populated.
10/12 SAML federation into the user pool. Reprints the SP box, creates the break-glass owner if needed, then asks "Path to the downloaded federation metadata XML file": drag the file into the terminal. Connects the provider as AlphaAgentSSO and redeploys the app stack; password sign-in is off from here. Done: "SAML provider present, client flipped, listener parameter set".
11/12 Create the first Organisation administrator. Creates the break-glass user and its owner record if step 10 did not; otherwise prints "<email> already exists; left untouched" and "<email> granted the owner role in alphaagent-org-admins".
12/12 Verify the installation. Runs doctor, read-only. Since 1.0.8 its services group first waits up to 15 minutes for the rollout steps 9 and 10 restarted ("waiting for the services to finish rolling out before judging them"; doctor --no-wait opts out). Done is "N passed, 0 failed" and the Done banner; the groups and their remediations: Troubleshooting the install.
=== Done ===
Console: https://org.example.com
Run `python3 orgctl.py status` for the installed state.
Run `python3 orgctl.py doctor` to verify the install end to end.
What you should see
python3 orgctl.py status prints the progress file path, a twelve-row table of steps with finish times, the SAML box, the Console hostname and Load balancer lines, and the live status of the six stacks; status --local skips the stack statuses and needs no AWS credentials. https://<hostname> redirects to your identity provider's sign-in page. Measured: about 20 minutes wall clock from the first prompt to the Done banner on the walk (the installer's own estimate for step 3 alone is 15 to 20 minutes; steps 8 and 12 wait up to 15 minutes each only when the services are slow to settle).
Other commands and flags
| Command or flag | Effect |
|---|---|
preflight, org-auth, foundation, push-image, seed-config, spa, app, settle, console-credential, saml, bootstrap-admin, doctor | Run one step on its own, to re-run or diagnose it. |
status [--local] | The installed state, as above. |
reset | Asks "Clear all of the above? This makes no AWS call." and empties the progress file; AWS is unchanged. |
teardown | Deletes everything the installer created here (six stacks, tables, buckets with contents, images, secrets with no recovery window, the user pool and its users, services, log groups, SSM parameter, Cloud Map namespace; never an org-target-account-role.yaml stack elsewhere) after you type the account id, the region and DESTROY; otherwise "teardown not confirmed - aborted. Nothing was deleted." Non-interactive: --yes plus --i-understand-this-deletes-everything. |
--region <code>, --profile <name> | The region (else AWS_REGION or AWS_DEFAULT_REGION, else the menu); a named credentials profile. |
--config <file> | Answers from JSON: region, environment, app_domain, cognito_prefix, acm_certificate_arn, vpc_cidr, break_glass_admin, console_credential, saml_metadata_path. An invalid value is fatal: "<key> = <value>: <problem>". |
--yes | Accept every default, never prompt; needs a region and a --config for answers without defaults; an existing Organisation is always resumed. |
--dry-run | No AWS write call; nothing is checkpointed. |
install --restart-from <step>, install --redo | Clear that checkpoint and every later one; re-run every step. |
--allow-data-loss | Upgrades only: let a stack update replace a data-bearing resource without confirmation; never implied by --yes. |
--skip-check <id> (preflight, install) | Skip one preflight check; the report prints "!! --skip-check suppressed: ... NOT checked and are NOT passing." |
--json (preflight, seed-config, doctor); doctor --no-wait; --help | JSON reports; judge the services without waiting for a rollout; every command and flag (install --help for one). |
ORGCTL_SETTLE_TIMEOUT, ORGCTL_STACK_TIMEOUT (environment variables) | Seconds settle waits for the services (default 900) and each stack operation may take (default 2400). |
Notes
- Stopping and resuming. Ctrl-C finishes the current step, prints "stopping before step N/12 (
<id>). re-run the same command to resume from where it stopped." and exits 130 (insidesettle, at once). Re-run the same command to resume; progress lives in.alphaagent-org-install.jsonbeside the bundle. - Resume menu, lock, state-file and timeout rules: Troubleshooting the install.