Skip to main content
Version: 1.0.11

Updating Studio

When Prometheus Research Labs publishes a new Studio release, you move your deployment to it with a single command: studioctl update. It auto-detects whether the release is a code-only change (just a new application image) or also changes infrastructure, and does the right thing — there are no options to choose. Updates reuse your saved configuration, so they are nearly hands-free.

Every update also re-applies your deployment's configuration so it stays in step with the release (for example, the AlphaAgent Console endpoint a release ships with). If any configuration value actually changes, Studio restarts the affected services — using the same safe, rolling, auto-rollback mechanism as a normal update — so the change reliably takes effect, and then verifies the deployment is healthy before reporting success. Nothing is rotated or regenerated, so this never disrupts a healthy deployment.

Before you update​

  1. Download the new release bundle from the Console and unzip it.
  2. Read the release notes for that version.
  3. Run studioctl from the new bundle folder, with credentials for your existing deployment's account and region.

To avoid colliding with automation, studioctl update guards a window of roughly one hour around your scheduled workflows — if a scheduled run is due inside that window, the update waits or warns rather than starting on top of it. Pick an update time that sits clear of your scheduled runs.

Knowledge Graph builds are interrupted by an update

An update performs a rolling restart of the Studio services. Any Knowledge Graph (AMPG) build that is in progress when you update is interrupted and will not complete. Wait for in-progress builds to finish before updating where you can, and re-run any interrupted Knowledge Graph build after the update completes.

studioctl remembers your previous answers (environment, domain, certificate, Cognito prefix, sizing tier, Redis node type, and model classes), so updates pre-fill almost everything. Neo4j is self-hosted, so there is nothing to enter.

You can also change infrastructure and model knobs during an update by passing the matching flag — for example --sizing (move up or down the five-tier ladder), --redis-node-type (resize the Redis cache), or --sonnet-model / --opus-model (swap a model class). Each is applied as a normal infrastructure/configuration change (services roll to the new task size or pick up the new config). To change only these knobs without moving to a new release, use studioctl reconfigure instead.

The update command​

python3 studioctl.py update

studioctl update takes no options — it figures out what the release needs and asks you to confirm anything consequential. It:

  1. Compares the new bundle against what is currently deployed.
  2. Always pushes the new Studio image and re-syncs the web app.
  3. Determines whether any infrastructure templates changed. If not, it performs a fast code-only update (just rolls the services to the new image). If they did, it proceeds with an infrastructure update. (You never pick which — an update with no infrastructure changes is automatically code-only.)
  4. Re-applies your configuration to match the release. If any value changed, every service is restarted so it picks the change up, and the deployment is verified healthy afterwards.

Code-only update (the common case)​

Routine version bumps usually change only the application. studioctl pushes the new image, optionally re-syncs the web app, and rolls the services. Each Studio service performs a rolling update, and a built-in safety mechanism monitors the rollout: if the new version fails to come up healthy, the update automatically rolls back to the previous version rather than leaving the service down. Your data stores, configuration, Neo4j, and networking are untouched.

Infrastructure update (when a release changes resources)​

When the release changes infrastructure (for example a new table or secret), studioctl computes a change set for each stack and shows you a reviewed summary of exactly what will be added, modified, or removed before anything is applied. Purely additive or in-place changes proceed once confirmed; any destructive change (a resource that would be replaced or deleted) is called out explicitly and requires a separate confirmation, so you are never surprised by data loss. Stacks that did not actually change resolve to a clean "no changes" and are left as-is.

Self-hosted Neo4j is carried forward across updates — its retained EFS storage and credentials are reused, so your graph survives the update.

Configuration is re-applied on every update​

Studio services read their configuration when they start, so a configuration change only takes effect once the affected services restart. To make this reliable, every update re-applies your deployment's configuration to match the release and then:

  • Detects what actually changed. Each configuration value is compared against what is currently deployed; unchanged values are left exactly as they are.
  • Restarts on any change. If anything changed, the affected services are restarted with the same rolling, auto-rollback-guarded mechanism used elsewhere, so the new configuration is picked up cleanly. If a release also ships a new image, that restart covers the configuration change too — services are not restarted twice.
  • Verifies afterwards. Once services settle, the update confirms each one is running the expected configuration and is healthy before reporting success.

Your existing connection details and credentials (including Neo4j and the deployment's internal signing keys) are reused as-is — re-applying configuration never rotates or regenerates them, so a healthy deployment is never disrupted. This is also the mechanism that rolls out a changed AlphaAgent Console endpoint to your running services.

Your data-connector credentials are protected​

The credentials you enter when you create a data connector (API keys, database passwords, and similar) are stored separately and owned by Studio at runtime — they are not part of the configuration a release ships. An update never re-seeds or overwrites them. As an extra safeguard, studioctl update:

  • Backs them up to your deployment's private, encrypted storage bucket before making any changes, and
  • Verifies they are byte-for-byte unchanged after the update completes.

In the extremely unlikely event the update detects any difference, it keeps the backup, warns you clearly, and prints a one-command restore — it never modifies your connector credentials on its own:

python3 studioctl.py restore-connector-creds          # restore from the most recent backup
python3 studioctl.py restore-connector-creds --from <backup>   # restore a specific backup

So you can update with confidence that connectors your team has set up will keep working.

What your users see during an update​

While an update is running, people who open Studio see a friendly maintenance screen instead of the app, letting them know AlphaAgent is being updated and will be back shortly. studioctl update turns this on automatically at the start of the run and clears it automatically when the run finishes — whether the update succeeded or failed — so users are never left looking at a half-updated app, and open browser tabs return to Studio on their own once it's done.

Users who already had Studio open in a tab before the update are handled too: the app periodically checks the running backend version (and re-checks whenever the tab regains focus). When it detects that the deployment has moved to a new version, it shows a brief "Studio was updated" banner and reloads itself automatically so everyone ends up on the new build without manually hard-refreshing. A "Refresh now" button is offered for anyone who wants to reload immediately.

There is nothing extra to run: the maintenance screen is part of update.

note

The maintenance screen activates the first time you run an update that includes infrastructure changes. Before that one-time step it is simply skipped and the normal app is shown.

If an update is interrupted in an unusual way (for example the machine running studioctl is killed mid-run), the maintenance screen could be left on. You can clear it — or turn it on for your own planned maintenance window — manually:

python3 studioctl.py maintenance off   # restore the normal app
python3 studioctl.py maintenance on    # show the maintenance screen

Reconfiguring without a version bump​

To change the sizing tier, the Redis node type, or a model class on a live deployment without moving to a new release, use studioctl reconfigure:

python3 studioctl.py reconfigure                                   # interactive: re-prompts the knobs
python3 studioctl.py --sizing large reconfigure                    # move up the sizing ladder
python3 studioctl.py --redis-node-type cache.r7g.large reconfigure # resize the Redis cache
python3 studioctl.py --opus-model anthropic.claude-opus-4-8 reconfigure  # swap the Opus class

reconfigure re-prompts (or takes the flags for) the sizing tier, Redis node type, and Sonnet/Opus model classes, reviews the resulting CloudFormation change sets, re-seeds the affected configuration, and rolling-restarts only what changed — all behind the same maintenance screen and auto-rollback safety as an update, but with no version bump (the deployed image is unchanged). Before adopting a different model you can also dry-run the checks with studioctl preflight, which re-runs the read-only Bedrock model-availability and tokens/day-quota checks for the models and sizing tier you specify.

A Redis node-type change is applied online but causes a brief failover/reconnect, so prefer to run it during a maintenance window.

Rolling back​

Updates are designed to be reversible.

  • Automatic. Before it changes anything, studioctl update records a restore point for your running services, and it only marks the new version as current after the deployment is verified healthy. If an update fails partway through while your credentials are still valid, it automatically rolls back to the previous working version.
  • Manual. If an update can't finish on its own — most commonly because your AWS session token expired mid-update — studioctl stops with a clear message instead of leaving things half-applied. Refresh your credentials and re-run studioctl update: completed work is skipped and it settles the deployment. To deliberately move back to an older release, run studioctl update from that older bundle — it is just an update in the other direction. (Your data stores are retained across updates, so they are never affected by a rollback.)

Updating single sign-on​

Changing your IdP metadata or attribute mappings does not require an image or infrastructure update — re-run just the SSO step:

python3 studioctl.py saml

See Single Sign-On (SAML).

After updating​

Browse to your domain to confirm the new version is serving, and check the Console license page — heartbeats continue across the update and the deployment should remain healthy. studioctl update already verifies configuration and health automatically before it finishes, so a clean run means your services are running the expected configuration. If a rollout did not go as expected, see Troubleshooting.