Skip to main content
Version: 1.0.11

Deploy walkthrough

This page walks through a fresh install of AlphaAgent Studio using the guided installer, studioctl. Make sure you have worked through the Prerequisites first. The installer is interactive, idempotent, and resumable — if it is interrupted (you press Ctrl-C, your laptop sleeps, or a transient AWS error occurs), simply re-run studioctl install and it picks up from the first step that has not completed. It remembers your non-secret answers between runs.

Before you start​

  1. Unzip the Studio release bundle you downloaded from the Console.
  2. Open a terminal in the unzipped folder.
  3. Export AWS credentials for your target account and region (environment variables or an AWS profile) with the required permissions.
  4. Have your License Token ready.

Running the installer​

From the bundle folder, run:

python3 studioctl.py install

studioctl is a single CLI with a subcommand per lifecycle task. With no command it prints an interactive menu listing the most common tasks (install, update, reconfigure, preflight, status, doctor, teardown, and exit). The full set of subcommands you can pass on the command line is:

  • install — fresh deployment (this page)
  • update — move to a new release — see Updating Studio
  • reconfigure — change the sizing tier, Redis node type, or model classes on a live deployment without a version bump — see Updating Studio
  • preflight — re-run the read-only quota and Bedrock model-availability checks at any time
  • restore-connector-creds — restore your data-connector credentials from an automatic pre-update backup — see Updating Studio
  • saml — (re)configure single sign-on — see Single Sign-On (SAML)
  • status — read-only summary of install progress, stack health, and recovery hints
  • doctor — verify configuration and health
  • maintenance on|off — manually show or hide the user-facing maintenance screen
  • teardown — permanently destroy the deployment and all its data (irreversible) — see Teardown

install and update take no command-specific flags — they are self-driving, detect what is needed, and ask you to confirm anything consequential. A few global flags (shared across commands) can preset the sizing tier, Redis node type, and model classes so you don't have to answer those prompts (handy for non-interactive runs).

Global flags (go before the command):

python3 studioctl.py --region <region> --profile <aws-profile> install
python3 studioctl.py --dry-run install      # print every action without changing anything
python3 studioctl.py --yes install          # non-interactive (with --config and env vars)
python3 studioctl.py --sizing standard install              # preset the Fargate sizing tier
python3 studioctl.py --redis-node-type cache.t4g.large install   # preset the Redis node type
python3 studioctl.py --sonnet-model anthropic.claude-sonnet-4-6 \
    --opus-model anthropic.claude-opus-4-6-v1 install       # preset the model classes

Other global flags include --config <answers.json> (preset answers as JSON) and --allow-destructive (permit replace/delete CloudFormation changes without prompting — use with care).

Before any work begins, the installer prints the AWS account, identity, and region it resolved, and asks you to confirm. Always check this matches your intended target.

The License Token is entered without echoing to the screen and is never written to disk. Your other answers (environment, domain, certificate, Cognito prefix, inference zone, sizing tier, Redis node type, and model classes) are saved locally so re-runs and updates pre-fill themselves.

You don't name anything internal. The project name (alphaagent) and the four CloudFormation stack names are fixed — the installer never asks for them and they can't be changed. This is deliberate: it removes the most common source of deployment mistakes (a name typed one way at install and another way at update). You only choose the inputs that are genuinely specific to your environment.

During configuration the installer also asks for a few infrastructure and model choices, all changeable later (with studioctl reconfigure or an update):

  • Sizing tier — one of five tiers (xs, small, standard (default, ~8–10 power users), large, xlarge). See Infrastructure costs and sizing → Sizing tiers.

  • ElastiCache (Redis) node type — defaults to cache.t4g.medium, with larger options available (cache.t4g.large, cache.m7g.large, cache.r7g.large, cache.r7g.xlarge, or any node type you type in). See Infrastructure costs and sizing → Redis node type.

  • Model classes — which Bedrock model fills the Sonnet (runner) and Opus (planner) classes. The installer offers a curated menu plus an "enter any model id" option:

    • Sonnet class — Claude Sonnet 4.6 (anthropic.claude-sonnet-4-6), the validated runner (default).
    • Opus class — Claude Opus 4.6 (anthropic.claude-opus-4-6-v1), the validated planner (default and recommended), or Claude Opus 4.8 (anthropic.claude-opus-4-8), the newest/strongest planner (verify Bedrock access and quota in your account first).

    See Prerequisites → Choosing your models.

Studio runs the Sonnet and Opus classes only — Haiku is not a permitted choice and is refused. The bare model id you choose is automatically zone-prefixed (us.* / eu.*) for your residency zone when the configuration secrets are seeded.

The steps of a fresh install​

1. Preflight​

The installer runs a read-only environment check: your identity, that the Console is reachable, that there are no conflicting pre-existing AlphaAgent resources, that Bedrock model access is enabled for the Sonnet and Opus models you chose (and that your tokens-per-day quotas meet the recommended floors for them), that your account's Fargate vCPU quota fits your chosen sizing tier, that your ACM certificate is ISSUED and covers your domain, and that your chosen Cognito prefix is available. If anything fails, it asks whether to continue (defaulting to no). Fix blockers before proceeding. You can re-run just these checks any time with studioctl preflight.

2. Foundation stack​

Creates the networking, data stores, container registry, Cognito user pool, and secret placeholders in your account. Your License Token is stored here as a one-time bootstrap secret so Studio can activate itself on first boot. This stack also provisions the encrypted, multi-AZ storage (EFS) that the self-hosted Neo4j service will use.

3. Neo4j credentials​

Neo4j is self-hosted — Studio runs a single-node Neo4j Community service in your VPC on Fargate for you (see Prerequisites). There is no manual pause: the installer generates a strong random password, stores it securely in Secrets Manager, and points Studio at the in-VPC Neo4j service (bolt://neo4j:7687). Zero-touch — nothing for you to launch or paste. On a resumed run the same password is reused (it is read back from the alphaagent-neo4j-credentials secret rather than regenerated).

4. Push the Studio image​

The installer loads the Studio application image from the bundle and pushes it to your ECR registry. This is the image your Fargate services will run.

5. Seed configuration secrets​

Populates Studio's configuration secrets in AWS Secrets Manager from the foundation stack's outputs and your Neo4j settings. This step also resolves the Bedrock model identifiers for your chosen Sonnet and Opus classes, zone-prefixed (us.* / eu.*) for your residency zone. Re-running is safe — existing security keys are preserved, never regenerated.

6. Upload the Studio web app​

Syncs the prebuilt Studio web application to its S3 bucket so it can be served through the load balancer.

7. Load balancer, compute, and services stacks​

Creates the internet-facing load balancer (with its SSO-enforcing listener), the Fargate cluster and roles, and the Studio service definitions — each stack building on the previous one. The self-hosted Neo4j service is created here too. When this completes, the Studio services start up on Fargate.

8. Configure single sign-on (required)​

Sign-in is SSO-only, so SAML setup is part of every fresh install. The installer prints the service-provider values you must register in your identity provider, then takes your IdP metadata and wires up the Cognito user pool and the load balancer's listener to require SSO. Full details, including the exact values and attribute mappings, are in Single Sign-On (SAML).

9. Verify configuration​

The installer runs a final read-only check (the same one available any time as studioctl doctor) that confirms each service resolved its configuration.

Finishing up​

The installer prints a DNS instruction: create a CNAME/ALIAS record pointing your domain at the load balancer's address. Create that record with your DNS provider. studioctl does not manage DNS; nothing is reachable until you create this record and your ACM certificate is validated/ISSUED. New records usually resolve within a few minutes, though propagation can occasionally take a little longer depending on your DNS provider and the record's TTL.

Then browse to your domain, complete SSO sign-in, and you are in Studio. Within a few minutes the running Studio activates and begins sending heartbeats, and the Console license page for your key turns healthy and starts reflecting usage. Because Neo4j is self-hosted and wired up automatically, knowledge-base features are available without any further steps. See Knowledge graphs in depth.

If something goes wrong​

The installer streams progress and stops on errors. Common issues (preflight failures, certificate problems, Cognito prefix collisions, Neo4j connectivity) are covered in Troubleshooting. Because the installer is resumable and idempotent, you can fix the underlying problem and re-run studioctl install; completed steps are skipped and it continues from where it stopped.

When you re-run install against a deployment that already exists, it recognises this and asks how you want to proceed:

  • Resume (default) — continue from the first step that did not complete.
  • Redo — run every step again from the start (safe; each step is idempotent).
  • Wipe and start over — completely tear down the partial deployment and install fresh. Because this destroys data, you must type a confirmation phrase, and it is never done automatically.

Credentials expiring mid-install? If your AWS session token expires partway through, the installer stops with a clear message and the exact command to continue — refresh your credentials and re-run studioctl install to resume from where it stopped. You will never be left with a half-applied step and a confusing error.