Install by blueprint (AWS)¶

The Calliope AI installer puts a pull-only Deployment Manager in your own AWS account. It asks which blueprint you want, records your answers, and then plans and applies the Terraform for each product from a console that runs in your account. This page covers what every blueprint shares: prerequisites, starting the Deployment Manager, the setup screens, applying from the console, and undoing an install. Each blueprint then has its own page.

Not yet validated end to end

These guides follow the installer's source as of release 0.1.57. No step on these pages has been validated end to end: none of the four blueprints has been applied, verified and torn down from a clean AWS account yet, and that acceptance run is still open. The steps stay here so you can follow and check them; until the run passes, read the known blockers before you start, and expect the console's own messages to be more current than this page.

The blueprints¶

The setup wizard opens on a catalog of cards. Each card is a preset over the same questions; it never decides anything the topology rules would refuse.

Card	Products	What it builds on AWS	Guide
Standalone (Astrolift ticked)	Astrolift	Its own VPC, Aurora cluster, Temporal, load balancer and EKS tenant cluster	Astrolift standalone
Zentinelle in Astrolift	Astrolift, Zentinelle	Astrolift as above; Zentinelle's backend, worker, console and its own Temporal as pods on Astrolift's tenant cluster, on Astrolift's network, Aurora cluster and load balancer	Zentinelle in Astrolift
Workbench on Astrolift	Calliope AI Workbench, Astrolift	The Workbench hub and user servers as pods on Astrolift's tenant cluster; Astrolift joins a network, ECS cluster, Aurora cluster and load balancer already in the account	Workbench on Astrolift
The Full loop	All three	The Workbench and Zentinelle on Astrolift's tenant cluster; Astrolift joins existing infrastructure, as above	The Full loop

The catalog also offers mixes without a guide here: All three, side by side, Zentinelle in Astrolift, Workbench beside, Astrolift and Zentinelle, side by side, the Astrolift controller outside or inside its own cluster, Restricted (agents only, on a cluster Astrolift is handed), and Mesh. Mesh starts as one install, the Workbench, Astrolift and Zentinelle side by side with nothing shared and Astrolift's controller on ECS, and grows from the console: Install adds Astrolift tenant clusters in this region or another under that one controller, and more Zentinelles and Workbenches. On AWS several of these mixes, Mesh included, join a VPC, ECS cluster, Aurora cluster and load balancer already in the account; each card says so.

Google Cloud and Azure appear on the cloud screen and cannot be selected yet. Everything on these pages is AWS.

Before you start¶

Every blueprint needs:

A host for the Deployment Manager. Linux or macOS with Docker running (Windows through WSL2). It reaches out to Calliope AI and to AWS; nothing reaches in. An air-gapped install, with no outbound call at all, is a separate and experimental path that these guides do not cover.
AWS credentials for the target account. The Deployment Manager applies Terraform under the credentials of its own process. On a laptop, the install script mounts $HOME/.aws read-only and forwards AWS_PROFILE, AWS_REGION, AWS_DEFAULT_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_SESSION_TOKEN by name. Setup checks them with sts:GetCallerIdentity and refuses to start without usable credentials. Refresh an SSO session on the host with aws sso login.
A Calliope AI sign-in with an organization, or permission to create one. Setup creates the deployment and its trial entitlement under your first organization.
A public Route 53 hosted zone dedicated to this deployment. Astrolift creates no zone; it manages the one you name in full, including a wildcard, and adds and removes records as apps and previews come and go. Delegate a subdomain such as apps.example.com rather than reusing a zone that serves anything else. The zone must be publicly resolvable so the certificate can validate, even if the addresses in it are private.
A deployment name: lowercase letters, digits and hyphens, starting and ending with a letter or digit, at most 16 characters. It names the state store, prefixes every resource and is chosen once.

Optional: install cosign on the host. With it, the script verifies the agent image signature before running it and refuses an image that fails; without it, it warns and continues.

Start the Deployment Manager¶

Select the target account's credentials, then print the command first. A dry run needs no Docker and launches nothing:

export AWS_PROFILE=<profile-for-the-target-account>
curl -fsSL https://install.calliope.ai/install.sh | sh -s -- --dry-run

Expected output, with your platform and paths:

Calliope AI platform installer (Build, Run, Observe, Control, Secure)
platform: Darwin/arm64   mode: web   image: public.ecr.aws/m6e9m8s0/workbench-installer:stable
mounting /Users/you/.aws read-only at /opt/calliope/.aws (the container user's ~/.aws); --no-aws withholds it
forwarding by name, values not shown or copied: AWS_PROFILE
dry run, nothing launched. This is the command (token redacted):
docker run --name calliope-agent -d -p 127.0.0.1:7080:7080 ... public.ecr.aws/m6e9m8s0/workbench-installer:stable web

The image is still named workbench-installer; that is the published name, not a stale one. Then run it:

curl -fsSL https://install.calliope.ai/install.sh | sh

The script pulls the image, verifies it when cosign is present, starts a container named calliope-agent with a named volume calliope-data, and ends with:

Setup UI: http://localhost:7080
Open it to finish setup. Follow along: docker logs -f calliope-agent

Useful flags, all from sh install.sh --help: --port (one of 7080, 7081, 7082, 8080, 8088, 9080 with the built-in sign-in app), --aws-dir PATH or --no-aws, --data-dir, --console off|health|full, --force to replace an existing calliope-agent container. The help text still says Zentinelle is not installable from the script; that sentence is out of date, and the setup screens offer it. On Linux, if the container cannot read your ~/.aws, resolve the profile on the host and let the variables carry it:

eval "$(aws configure export-credentials --profile <profile> --format env)"
curl -fsSL https://install.calliope.ai/install.sh | sh

The setup screens¶

Open http://localhost:7080. The screens are the same for every blueprint; what each blueprint presets is on its own page.

Set up Calliope AI in your cloud. Sign in with your Calliope AI account.
Choose what to install. Pick a card and accept the terms. For Standalone, tick the products under "Standalone: which products".
Pick the cloud. AWS, and the region: one from the list, or Other and its region code.
Pick a footprint. Lean, Balanced (recommended), Performance or Secured. Lean is one NAT gateway, no interface endpoints, no Container Insights, no flow logs, and a Spot tenant runtime with one on-demand anchor node. Footprint can be changed later from the console.
Review the drawing. The answers the card set are marked. Advanced holds the rest: tenant runtime, hostnames (short hub, astro, zen by default), where Astrolift answers (the apps domain itself by default), databases pausing when idle (default), app sign-in, and the others.
What we need from you. The values the plan cannot infer. Each blueprint page lists them.
Before we start. What you must supply, what will be created and what bills at rest. Submitting creates the deployment in Calliope AI and enrolls the Deployment Manager.
Setup complete, with Open the Deployment Manager. The console takes over the same address.

Setup runs once per data volume. A second run on an enrolled volume is refused, because it would create a second deployment and trial in Calliope AI; install another deployment on a fresh volume (--data-dir).

Apply from the console¶

The console (on screen, Deployment Manager) has five pages: Status, Install, History, Agent and Teardown. It binds to loopback; reach a remote one with ssh -N -L 7080:localhost:7080 you@host or kubectl port-forward.

Each blueprint is one or more units, each with its own Terraform state. Install lists every unit under Dry runs as a row named Plan and the unit, for example Plan Astrolift; the guides call a step by that row's name. For each unit, in the order its guide gives:

Press Dry run on the unit's Plan row. The plan is saved as that unit's plan of record and nothing is created.
Read it. A plan that deletes or replaces a stateful resource (databases, file systems, buckets, keys, secrets, the Cognito pool) is drawn in red, names what it removes, and needs a second confirmation.
Press Deploy on the unit's row under Deploy. Deploy applies exactly the plan it was drawn for, by digest; a plan older than 24 hours is refused, so dry run it again. Post-apply phases run before the job completes; for Astrolift that includes the database bootstrap task.

The Deployment Manager holds one request and runs one job at a time. A unit that stands on Astrolift is drawn unavailable, with the reason, until Astrolift's apply is recorded. History keeps every job; ?job=<id> shows one in full.

With anything withheld from Astrolift (the Restricted card, or "What Astrolift may manage" under Advanced), Astrolift's plan also names any existing astrolift-* role that already holds a withheld capability, and what to run to re-mint it. Nothing changes those roles for you. The four blueprints here withhold nothing.

Undo¶

Use Teardown, never a local terraform destroy:

Each unit offers keep data (also the first half of a rebuild) and with data. Every teardown needs the deployment name typed; destroying data also needs destroy data typed.
A teardown is a destroy plan you read and then deploy, like any other plan.
The tab enforces the removal order: units that stand on Astrolift first, Astrolift last.
What the install did not create is kept and listed: the hosted zone you delegated and the records Astrolift left in it, and on the blueprints that join existing infrastructure the VPC, Aurora cluster, load balancer, listener and certificate you supplied.
Once every unit has had a with data teardown deployed, the tab offers Retire this deployment, behind the typed name as well. Retiring tells Calliope AI, which frees the seats and revokes the Deployment Manager's key; the Deployment Manager then stops its heartbeat, polling and license refresh and clears the key it holds. It cannot be undone from the console; a new install enrolls a new Deployment Manager. A keep-data teardown never offers it, because it is the first half of a rebuild.
The last steps are yours: the in-account state store, then the Deployment Manager itself. On the Docker path, docker rm -f calliope-agent stops it; docker volume rm calliope-data removes its record and credentials. If it ran under a role created for it, delete the role and its permissions boundary.

Known blockers¶

Read in the installer source as of release 0.1.57; each one stops a clean-account run before the first app.

No state store on a fresh deployment. The first plan initializes Terraform against an S3 bucket <deployment>-junohub-tfstate-<account-id> and lock table <deployment>-junohub-locks in your account. The job that creates them exists in the Deployment Manager, but the console does not offer it and Calliope AI may no longer start it (the Deployment Manager only accepts read-only status work from outside). On a fresh account the first dry run therefore has no state store to initialize against.
App sign-in default needs an identity provider the wizard does not collect. On AWS the "App sign-in" answer defaults to one sign-in for every app (Envoy Gateway). Astrolift's Terraform requires a Cognito identity provider (idp_kind, cognito_user_pool_id, idp_client_id) with that answer, and no setup or console screen asks for one, so the plan's input contract refuses it.
No first Astrolift administrator. Astrolift creates its first administrator from admin_email on boot. The wizard asks the Workbench's admin email only, so an Astrolift install from the wizard renders none.

The Workbench on Astrolift and Full loop cards add a fourth prerequisite rather than a blocker: on AWS they join a VPC, ECS cluster, Aurora cluster and load balancer that already exist in the account.

Installing Astrolift covers the open Terraform and Helm runbooks in astrolift-opscode, for installing without the Deployment Manager.
Operator quickstart covers the CLI, cluster registration and a first app.
Runbooks cover failures by symptom.