AWS Bootstrap (recommended)

The fastest way to a production formae agent on AWS is the open-source formae-bootstrap installer. One command stands up the whole agent — VPC, ECS Fargate task, and a PostgreSQL datastore — secure by default.

formae runs as a client and an agent: you use your local install to provision the agent's permanent home in the cloud, then point your CLI at it with a profile and hand off. See the architecture overview for the client/agent model.

Choose an access mode:

alb — public HTTPS endpoint fronted by an ALB using your ACM certificate. Requires a domain you own.
tailnet — private, reachable only over your Tailscale tailnet; the agent serves a trusted *.ts.net certificate. No public ingress.

Basic auth is on in both. Follow the tab for your chosen mode below.

Prerequisites

The formae CLI, matching the agent image version — see local installation.
AWS credentials for the target account.
openssl and htpasswd (from apache2-utils / httpd-tools) or docker, to generate the basic-auth credential.

Clone the installer:

git clone https://github.com/platform-engineering-labs/formae-bootstrap.git
cd formae-bootstrap

Install

albtailnet

Also needs: a domain you own and an ACM certificate for it — status ISSUED, in the same region as the ALB. Note the certificate ARN.

1. Generate the API credential. Basic auth validates a bcrypt hash, produced locally:

aws/scripts/gen-api-credential.sh

Keep the printed password for step 4; the hash goes to the apply.

2. Apply. RDS spin-up is the long pole (~10 min); --watch streams progress.

formae apply --mode reconcile aws/bootstrap.pkl \
  --access alb --region <region> \
  --cert-arn <acm-arn> --domain agent.example.com \
  --api-user formae --api-password-hash '<hash from step 1>' \
  --watch --status-output-layout detailed

To restrict who can reach the ALB, add --allow-cidr <cidr> (open by default).

3. Point DNS at the ALB. Add agent.example.com → the ALB's DNS name (a Route53 alias record, or a DNS-only CNAME elsewhere). Connect via https://<your-domain>, not the raw *.elb.amazonaws.com name — the certificate only matches your domain.

4. Connect.

aws/scripts/write-bootstrap-profile.sh --profile bootstrap \
  --domain agent.example.com --user formae --password '<password from step 1>'
formae status agent --profile bootstrap

Also needs: a Tailscale tailnet with a tag:formae tag, HTTPS certificates enabled, and a reusable auth key carrying that tag:

Sign in at login.tailscale.com/start with an identity provider — the free Personal plan is enough. Note your tailnet name (e.g. tailXXXX.ts.net).
DNS tab: enable MagicDNS and HTTPS Certificates (required for the *.ts.net certificate).
Access controls → Tags → Create tag: name it formae (no tag: prefix), owner = yourself.
Settings → Keys → Generate auth key: Reusable on, Ephemeral off, Tags → tag:formae. Copy the tskey-auth-… value.

1. Generate the API credential.

aws/scripts/gen-api-credential.sh

Keep the printed password for step 3; the hash goes to the apply.

2. Apply. RDS spin-up is the long pole (~10 min); --watch streams progress.

formae apply --mode reconcile aws/bootstrap.pkl \
  --access tailnet --region <region> \
  --ts-authkey '<tskey-auth-…>' --ts-hostname formae-bootstrap \
  --api-user formae --api-password-hash '<hash from step 1>' \
  --watch --status-output-layout detailed

The agent joins your tailnet as <ts-hostname>.<your-tailnet>.ts.net and serves the API over a trusted certificate on port 49684. Confirm it joined in the Tailscale admin console → Machines.

3. Connect. Your CLI machine must be on the same tailnet (a device can be on only one at a time — use tailscale switch / tailscale login to reach it):

aws/scripts/write-bootstrap-profile.sh --profile bootstrap --access tailnet \
  --fqdn formae-bootstrap.<your-tailnet>.ts.net --user formae --password '<password from step 1>'
formae status agent --profile bootstrap

Next steps

Operating the agent — updating, rolling back, shelling in, teardown, and production tuning.
Authentication — basic-auth details.
Need full manual control of the ECS service and networking, or to integrate with existing infrastructure-as-code? See the Standard ECS walkthrough.

Reference

Flags for formae apply … aws/bootstrap.pkl:

Flag	Mode	Notes
`--access`	both	`alb` (default) or `tailnet`
`--region`	both	region for the apply
`--size`	both	Fargate t-shirt size (see below); default `small`
`--database`	both	`new` (default) provisions RDS; `existing` uses your DB (with `--db-host` / `--db-user` / `--db-name` / `--db-password-secret-arn`)
`--formae-image`	both	agent image reference — the version knob
`--api-user`	both	basic-auth username (default `formae`)
`--api-password-hash`	both	bcrypt hash from `gen-api-credential.sh`
`--cert-arn`	alb	ACM certificate ARN (same region)
`--domain`	alb	hostname clients connect to; must match the certificate
`--allow-cidr`	alb	restrict ALB ingress to one CIDR (open by default)
`--ts-authkey`	tailnet	reusable Tailscale auth key
`--ts-hostname`	tailnet	tailnet (MagicDNS) hostname (defaults to the stack name)

Passing a flag that belongs to the other mode fails fast with a clear message.

Sizing

--size maps to a Fargate-valid CPU/memory pair. Memory has a ~2 GB floor regardless of inventory size, because the agent image loads all its bundled resource plugins at once.

size	vCPU / memory	rough capacity
`small`	0.5 / 2 GB	up to ~1,000 resources
`medium`	1 / 2 GB	~1,000–5,000
`large`	2 / 4 GB	~5,000–10,000
`xlarge`	4 / 8 GB	~10,000–20,000