Deploy an M8trx agent via GUI (m8trx-deployer)

The fastest path to "click → customer agent live, telemetry flowing to brain." All steps are GUI clicks across three consoles: m8trx- deployer, Tailscale admin, AWS console. Zero terminal.

Big-picture flow (what you're doing): mint a Tailscale key tagged for this customer → mint a brain bearer key → drop both in AWS SSM → click Deploy in m8trx-deployer → approve the new device in Tailscale. ~5 minutes, 6 clicks.

Before you start (one-time fleet setup)

You only do this section once per AWS region. Skip if it's already done.

Tailscale ACL configured (Tailscale → Access Controls). The ACL JSON includes M8trx tags + isolation rules. Template at agent-artifacts/cloud-init/README.md § Tailscale ACL. Copy-paste, save.
Tailnet Lock enabled (Tailscale → Settings → Tailnet Lock → Enable). Adds the "approve new device" gate.
AWS fleet IAM applied (any Terraform runner). Apply the m8trx-fleet module (README) with brain_url = "http://brain.tailnet.ts.net:8080". Creates the IAM role + instance profile every customer agent uses.

If m8trx-deployer's setup wizard hasn't done these yet, it can either run them on your behalf or surface a one-time setup checklist that links each item to its console.

Per-customer agent — 6 GUI clicks

For each new customer (or each new agent for an existing customer). Customer ID format is cust_<lowercase_letters_digits_underscores>, e.g. cust_acme.

1. Tailscale console — add the customer's tag + ACL rule

Console: Tailscale → Access Controls

Open the ACL JSON. Add two lines:

"tagOwners": {
  "tag:m8trx-cust-acme": ["autogroup:admin"],
  ...
},
"acls": [
  { "action": "accept", "src": ["tag:m8trx-cust-acme"], "dst": ["tag:m8trx-cust-acme:*"] },
  ...
]

Replace acme with the customer ID minus the cust_ prefix. Save.

(Skip if you already have a tag for this customer.)

2. Tailscale console — mint the customer's auth key

Console: Tailscale → Settings → Keys → Generate auth key

Settings:

Reusable: ✓
Ephemeral: ✓
Tags: tag:m8trx-cust-acme (the tag from step 1)

Click Generate. Copy the tskey-auth-... value. You'll paste it in step 3.

3. AWS console — store the Tailscale key in SSM

Console: AWS → Systems Manager → Parameter Store → Create parameter

Settings:

Name: /m8trx/cust_acme/tailscale-auth-key
Type: SecureString
Value: paste the tskey-auth-... from step 2

Click Create.

4. m8trx-deployer — mint brain bearer + store in SSM

Console: m8trx-deployer dashboard

Click Mint brain key (or whatever the deployer calls it). Provide:

Customer ID: cust_acme
Display name: "Acme Corp" (whatever you want shown in dashboards)

The deployer hits brain's mint-key.js API and writes the result to SSM at /m8trx/cust_acme/brain-key.

If your m8trx-deployer doesn't yet integrate brain's mint-key endpoint: do this in two manual clicks via AWS console + brain SSH. See docs/runbook-connect-customer-ec2.md § Per-customer onboard checklist steps 3–4 for the exact commands.

5. m8trx-deployer — click Deploy

Console: m8trx-deployer dashboard → "Deploy customer agent"

Provide:

Customer ID: cust_acme
AWS region: (whichever you've populated SSM in)
Subnet / security group: the deployer's VPC defaults are fine

The deployer runs the m8trx-agent Terraform module (README) under the hood. ~2 minutes to provision the EC2.

6. Tailscale console — approve the new device

Console: Tailscale → Devices

The new EC2 appears as ip-10-x-x-x (or similar) with a "Tailnet Lock: not signed" badge. Click Sign device. The device comes online in the customer's tailnet namespace immediately.

Verify (optional)

5 minutes after step 6, the agent's first heartbeat lands at brain.

m8trx-deployer dashboard should show the agent as "online" (if the deployer integrates brain's customers/agents endpoint).
brain dashboard at http://<brain-tailscale>:8080/ → FLEET TELEMETRY tab should show the customer with last seen ≤ 5 min and a heartbeat row in postgres.

If nothing arrives after ~10 min: see docs/runbook-connect-customer-ec2.md § "If something failed" for the diagnostic recipe.

What m8trx-deployer could integrate to compress this further

Each integration shaves a console-bounce from the operator flow:

Integration	Removes	Effort
Tailscale API: ACL JSON edit	Step 1	Low — Tailscale REST API
Tailscale API: mint auth key	Step 2	Low — Tailscale REST API
AWS SSM put-parameter (Tailscale key)	Step 3	Trivial — AWS SDK
brain mint-key.js + SSM put	Step 4 (already partially scoped)	Medium — exec into brain or expose mint endpoint
Terraform runner (m8trx-agent module apply)	Step 5 already in deployer	(Ship the deployer feature)
Tailscale API: approve device in Tailnet Lock	Step 6	Low — Tailscale REST API

Full integration → operator clicks one button on the deployer ("Deploy agent for cust_acme") and the deployer handles all 6 steps internally. The current artifacts (Terraform modules, cloud-init bootstrap, brain mint-key) are designed to be wrapped exactly this way.