Install Compass in your AWS account

One package. One sentence to your AI agent, or three commands. About 20 minutes, most of it waiting for AWS. Compass runs entirely inside your account; nothing leaves it.

Simple install

With your AI agent: one sentence

Works with Claude Code, Claude Desktop and Cursor. The package registers an MCP server and, for Claude Code, a set of skills (playbooks). From then on your agent can install, configure and operate Compass.

# 1. install the package
npm i -g @beamreach/compass

# 2. register it with your agent (claude-code | claude-desktop | cursor)
compass agent install

# 3. start your agent and say:
"Set up Compass in my AWS account, arm it with honeypots, and scan it."

The agent checks prerequisites, shows you a plan with the estimated monthly cost, asks for the admin email and one yes, and then runs the install. About 8 to 15 minutes later it connects the account as the scan target, starts the first security and FinOps audits, and reports back. Connecting GitHub (one browser click, see below) unlocks the infrastructure map, honeypot suggestions and pull requests. Afterwards you talk to it:

• "What did Compass find overnight?"
• "Open fix PRs for everything rated safe."
• "Add a Slack channel for honeypot alerts and test it."
• "Who tripped the IAM canary at 3am?"

Without an agent: three commands

npm i -g @beamreach/compass
compass install check-prereqs                           # credentials, VPCs, Bedrock; says if --create-network is needed
compass install --admin-email [email protected]          # prints the plan with the cost estimate, nothing created
compass install --admin-email [email protected] --yes    # creates the stack (~15 min)
compass status

If the check finds no VPC with private subnets behind a NAT gateway (a default VPC only has public subnets), add --create-network to both install commands. Pass --region and --aws-profile on every command if you do not want the AWS CLI defaults.

The install writes a profile to ~/.config/compass/config.json with the URL and an API token it minted for you, so every later command just works. The dashboard login is printed at the end: username admin, password stored in Secrets Manager (the output names the secret).

Advanced install

CloudFormation, step by step

The CLI launches a public CloudFormation template. You can launch the same template yourself, from the console or the AWS CLI, and connect the CLI afterwards. This is also the path for HTTPS with Cognito login and for scanning other accounts.

1. Network

The stack needs a VPC with public subnets in two availability zones (for the load balancer) and private subnets in two zones with NAT egress (for the workers). If you do not have one, launch compass-network.yaml first; its outputs are the subnet ids for step 2.

aws cloudformation create-stack --stack-name compass-network \
  --template-url https://beamreach-marketplace-assets.s3.amazonaws.com/cloudformation/latest/compass-network.yaml

2. The Compass stack

aws cloudformation create-stack --stack-name compass --capabilities CAPABILITY_NAMED_IAM \
  --template-url https://beamreach-marketplace-assets.s3.amazonaws.com/cloudformation/latest/compass-cloudformation.yaml \
  --parameters \
    ParameterKey=VpcId,ParameterValue=vpc-0123 \
    ParameterKey=PublicSubnetIds,ParameterValue=\"subnet-a,subnet-b\" \
    ParameterKey=PrivateSubnetIds,ParameterValue=\"subnet-c,subnet-d\" \
    ParameterKey=AdminEmail,[email protected] \
    ParameterKey=LocalIamMode,ParameterValue=true

Outputs you will use: ApiUrl, LoadBalancerDnsName, AppPasswordSecretArn, BootstrapTokenSecretArn.

3. Connect the CLI

Anyone who can read the bootstrap secret is an admin. The CLI reads it with your AWS credentials and mints a personal token; no copy and paste.

compass login --from-aws --stack-name compass
compass doctor
compass account connect --mode local_iam      # or --mode assume_role --account-id 1234… for another account

4. HTTPS and Cognito login (optional)

Request or import an ACM certificate for your domain in the same region, pass AcmCertificateArn and AppDomainName, then create a CNAME (or Route 53 alias) from the domain to LoadBalancerDnsName. The CLI does the DNS for you when the hosted zone is in the same account: compass install set-dns compass.example.com --yes. Cognito emails the admin a temporary password; users and roles (admin, operator, viewer) are managed in the user pool.

5. Scan another account

Deploy the target role in that account (read-only or remediate tier), then register it:

compass account role-template                     # quick-create link + CLI command for the other account
compass account role-template --deploy --aws-profile other-account --yes
compass account connect --mode assume_role --account-id 123456789012

6. GitHub (one click, needed for the map and pull requests)

The infrastructure map joins your AWS resources to the Terraform that owns them, so it starts once GitHub is connected; honeypot suggestions, triage, fixes, imports and drift fixes build on the map and are delivered as pull requests. compass github connect prints a link; open it in a browser once to install the GitHub App on your organisation. Security and FinOps audits, findings, notifications, compliance and policies work without it.

AWS Marketplace

Compass is also listed on AWS Marketplace as a container product. The Marketplace launch uses the same template; after the stack completes, continue from step 3.

Uninstall

compass uninstall                                  # the removal plan, nothing deleted
compass uninstall --confirm-stack-name compass     # removes the stack, DNS and network it created, workspace secrets, the local profile
compass uninstall verify                           # anything still tagged beamreach:managed

If the install never finished (no profile was written), add --stack-name <name> --region <region> to both uninstall commands; the network stack the installer created (<name>-network) is removed with it.

Honeypots planted through pull requests get removal pull requests; the canaries disappear when you merge them. Pull requests Compass opened stay yours. If a GitHub App was created for Compass, delete it in GitHub settings. Nothing phones home after removal.