Multiplayer agent harness for work.
feat: Porter deployment onboarding — checklist, deploy reference, guardrails
Josh France93ac1c93e153
diff --git a/.codex/skills/deploy-qm/references/porter.md b/.codex/skills/deploy-qm/references/porter.mdnew file mode 100644index 000000000..4a1b96704--- /dev/null+++ b/.codex/skills/deploy-qm/references/porter.md@@ -0,0 +1,5 @@+# Porter deployment++Read+[`../../../../cli/templates/deployment/references/porter.md`](../../../../cli/templates/deployment/references/porter.md)+completely and follow it.diff --git a/cli/src/secrets.ts b/cli/src/secrets.tsindex ae6585065..d0291789e 100644--- a/cli/src/secrets.ts+++ b/cli/src/secrets.ts@@ -137,7 +137,10 @@ export const FIRST_PARTY_SECRET_SPECS: readonly SecretSpec[] = [],},},- description: "Porter API token for the sandbox backend and the per-deployment app publisher.",+ description:+ "Admin-role Porter API token for the sandbox backend and the per-deployment app publisher — Developer-role tokens fail mid-deployment with PERMISSION_DENIED.",+ generate:+ "create an Admin-role API token in the Porter dashboard (https://dashboard.porter.run → Settings → API tokens)",},{name: "SPRITES_TOKEN",diff --git a/cli/templates/deployment/deployment.md b/cli/templates/deployment/deployment.mdindex 857129e32..7b8cbacb3 100644--- a/cli/templates/deployment/deployment.md+++ b/cli/templates/deployment/deployment.md@@ -15,9 +15,12 @@ Before cloud mutation, read `qm.config.jsonc` when it exists. Its `target` isthe selected provider; confirm it with the operator and do not offer to changeit in place. If the repository has not been initialized, collect:-- hosting target: a cloud provider, Fly.io or AWS. Recommend Fly.io when the- operator has no preference. The docker target runs everything on the local- machine, is for a quick local test drive only, and is outside this+- hosting target: a cloud provider — Fly.io, AWS, or Porter. Recommend Fly.io+ when the operator has no preference. Porter deploys onto a Kubernetes+ cluster in the operator's own cloud account and has no `qm` CLI target:+ choosing it switches this workflow to `references/porter.md`, which drives+ the Porter CLI and dashboard directly. The docker target runs everything on+ the local machine, is for a quick local test drive only, and is outside thisworkflow; never present it as the recommended path for a real deployment;- the first administrator's verified work email;- how people sign in: the built-in `auth` broker, which emails a one-time link,diff --git a/cli/templates/deployment/references/porter.md b/cli/templates/deployment/references/porter.mdnew file mode 100644index 000000000..1ffa8be17--- /dev/null+++ b/cli/templates/deployment/references/porter.md@@ -0,0 +1,73 @@+# Porter deployment++Use this after the choices and billing confirmation in `deployment.md`. Porter+has no `qm` CLI target: `setup`, `plan`, and `up` do not drive it. The flow is+the Porter CLI plus the repo's `porter/apps/` templates, with `docs/porter.md`+as the reference for every failure mode named below.++## Preflight++Install the [Porter CLI](https://docs.porter.run/cli/installation) and prefer+it over raw API calls wherever a command exists. Require Docker Buildx too —+every image must be built `--platform linux/amd64`:++```bash+porter auth login+porter config set-project <project-id>+docker buildx version+```++Three dashboard steps come before any cluster, in this order. Do them through+the operator's browser when you have browser access; otherwise give the+operator the exact URL and wait:++1. **Cloud account.** A cloud account must be linked to the Porter project at+ <https://dashboard.porter.run/cloud-accounts>. Check before prompting: with+ a token, `GET <PORTER_DEPLOY_URL>/api/v2/alpha/projects/<project>/cloud-accounts`+ lists linked accounts and their connection state. If none is connected, the+ operator links one themselves — the flow grants Porter IAM roles via a+ CloudFormation stack (or the Azure/GCP equivalent) in their own cloud+ console, and no agent should drive that unattended. Field gotchas: the AWS+ quick-create link opens in `us-east-2`, so a region-pinning SCP fails the+ stack with an explicit deny (reopen the same URL under the permitted+ region), and the account ID Porter wants is the one in the AWS console's+ top-right menu, not whatever the operator's CLI is logged into.+2. **Admin API token.** Mint an **Admin-role** token under Settings → API+ tokens and record `PORTER_DEPLOY_PROJECT_ID` and `PORTER_DEPLOY_CLUSTER_ID`.+ A Developer token survives every read and then dies mid-deployment with+ `PERMISSION_DENIED`, and cannot delete clusters — check the role before+ provisioning anything the operator will later need to remove.+3. **Cluster contract.** Create the cluster with the sandbox load balancer,+ `sandboxesEnabled`, and the apps root domain already in the creation+ contract (`docs/porter.md` → "Giving published apps stable hostnames").+ Attaching them after creation is the wedged-cluster path.++## Configure the administrator before first boot++The workflow's step 1 collected the administrator's email; on Porter nothing+derives the env vars from it, so set them by hand on core before the first+apply:++```bash+ADMIN_GRANTS=<email>:org_admin+AUTH_ALLOWED_EMAILS=<email>+```++With Postgres and no `ADMIN_GRANTS`, the instance boots, sign-in works, and+the admin console is permanently unreachable — there is no in-product way to+grant the first admin afterwards. The Helm chart bridges `AUTH_ALLOWED_EMAILS`+to the portal's `OIDC_ALLOWED_EMAILS`; on the raw `porter/apps/` path set both.++## Build, deploy, verify++```bash+for f in porter/apps/*.yaml; do porter apply -f "$f"; done+```++Apply runs once per app file, twice overall — assigned hostnames land on the+second pass. Then hand-wire the six service URLs per the table in+`docs/porter.md` ("Hosting the qm surfaces"), push secrets as Porter env+groups, and verify by signing in as the administrator and opening the Admin+tab. Published-app serving needs nothing further: apps are reachable+signed-in at `/d/<app>/`; setting `DEPLOY_APPS_DOMAIN` upgrades them to+per-app subdomains (`docs/porter.md`, onboarding checklist).diff --git a/cli/test/package.test.ts b/cli/test/package.test.tsindex e4b9c0e06..461171622 100644--- a/cli/test/package.test.ts+++ b/cli/test/package.test.ts@@ -285,6 +285,7 @@ else if (command === "secretsmanager get-secret-value") {assert.ok(packed[0]!.files.some(({ path }) => path === "templates/aws/microvm-agent/agent.mjs"));assert.ok(packed[0]!.files.some(({ path }) => path === "templates/deployment/deployment.md"));assert.ok(packed[0]!.files.some(({ path }) => path === "templates/deployment/references/fly.md"));+ assert.ok(packed[0]!.files.some(({ path }) => path === "templates/deployment/references/porter.md"));assert.ok(packed[0]!.files.some(({ path }) => path === "templates/fly/core.toml"));assert.ok(!packed[0]!.files.some(({ path }) => path === "src/contract.ts" || path === "bin/qm.ts"));} finally {diff --git a/docs/porter.md b/docs/porter.mdindex fb95bec40..290081ac2 100644--- a/docs/porter.md+++ b/docs/porter.md@@ -10,11 +10,54 @@ AWS, GCP, or Azure account. qm can use it two ways, independently:Both need a Porter API token and the project and cluster that own the sandbox API:```bash-PORTER_DEPLOY_API_TOKEN=<api token from Settings -> API tokens>+PORTER_DEPLOY_API_TOKEN=<ADMIN-role api token from Settings -> API tokens>PORTER_DEPLOY_PROJECT_ID=<project id>PORTER_DEPLOY_CLUSTER_ID=<cluster id>```+## Onboarding checklist++Everything below this section is reference and field notes; this is the order that+actually gets a new operator from zero to a working instance (the deployment workflow's+agent-facing version lives at `cli/templates/deployment/references/porter.md`). If you are an agent doing+this deployment: install and prefer the `porter` CLI over raw API calls wherever a+command exists ([install instructions](https://docs.porter.run/cli/installation)); use+the operator's browser for the dashboard steps when you have browser access, and+otherwise hand the operator the exact URL and wait — several steps below cannot be done+any other way.++1. **A cloud account must be linked to the Porter project** at+ [dashboard.porter.run/cloud-accounts](https://dashboard.porter.run/cloud-accounts)+ before any cluster can exist. Check first — with a token,+ `GET <PORTER_DEPLOY_URL>/api/v2/alpha/projects/<project>/cloud-accounts` lists linked+ accounts and their connection state; without one, look at the dashboard page. If none+ is connected, the operator has to link one themselves: the flow grants Porter IAM+ roles via a CloudFormation stack (or the Azure/GCP equivalent) in _their_ cloud+ console, which no agent should drive unattended. Two AWS gotchas from the field: the+ quick-create link opens in `us-east-2`, so an org SCP that pins regions makes the+ stack fail with an explicit deny — reopen the same URL under the permitted region —+ and the account ID Porter wants is the one shown in the AWS console's own top-right+ menu, not whatever account the operator's CLI happens to be logged into.+2. **Mint an Admin-role API token** (Settings → API tokens) and record+ `PORTER_DEPLOY_PROJECT_ID` and `PORTER_DEPLOY_CLUSTER_ID`. The role matters: a+ Developer token survives every read until it dies mid-deployment with+ `PERMISSION_DENIED` (details under egress below) and cannot delete clusters. Check+ the role before provisioning anything you will later need to remove.+3. **Create the cluster with the sandbox load balancer in the creation contract** —+ sandbox ingress, `sandboxesEnabled`, and the apps root domain all belong in the+ contract the cluster is born with; attaching them later is the wedged-cluster+ forensics that "Giving published apps stable hostnames" below exists to debug.+4. **Name the administrator before first boot.** Set `ADMIN_GRANTS=<email>:org_admin`+ on core and the sign-in allowlist (`AUTH_ALLOWED_EMAILS=<email>` — the Helm chart+ bridges it to the portal's `OIDC_ALLOWED_EMAILS`). This is the step the old docs+ never mentioned: with Postgres and no `ADMIN_GRANTS`, the instance boots, everyone+ allowed can sign in, and the admin console is permanently unreachable — there is no+ in-product way to grant the first admin afterwards.+5. **Build, push, and apply**: images built `--platform linux/amd64`, then+ `for f in porter/apps/*.yaml; do porter apply -f "$f"; done` (twice — the hostname+ lands on the second pass), then wire the service URLs per the table below. Verify by+ signing in as the admin and opening the Admin tab.+## Hosting the qm surfaces`porter/apps/` declares the six services (core, auth, web-ui, admin, portal,diff --git a/src/index.ts b/src/index.tsindex 817889b5c..34eaa49d1 100644--- a/src/index.ts+++ b/src/index.ts@@ -44,6 +44,12 @@ if (config.deployAppsDomain) {});}+if (config.databaseUrl && !config.adminGrants) {+ console.warn(+ "[qm] ADMIN_GRANTS is unset with a durable store — if this deployment has never named an admin, the admin console is unreachable and cannot be unlocked from inside the product; set ADMIN_GRANTS=<email>:org_admin (ignore this if an admin was already promoted in the Users tab).",+ );+}+if (config.deployProvider === "docker") {void dockerDaemonFailure().then((failure) => {if (failure)diff --git a/test/deployment-skill.test.ts b/test/deployment-skill.test.tsindex 4ef25e261..efc0a7f5d 100644--- a/test/deployment-skill.test.ts+++ b/test/deployment-skill.test.ts@@ -11,7 +11,7 @@ test("package-consumer deployment skill covers both self-owned providers and theconst root = read("cli/templates/deployment/deployment.md");for (const phrase of ["Before cloud mutation",- "Fly.io or AWS",+ "Fly.io, AWS, or Porter","deployment repository","npm ci","slack render",@@ -36,6 +36,7 @@ test("package-consumer deployment skill covers both self-owned providers and the".codex/skills/deploy-qm/agents/openai.yaml",".codex/skills/deploy-qm/references/fly.md",".codex/skills/deploy-qm/references/aws.md",+ ".codex/skills/deploy-qm/references/porter.md",".codex/skills/deploy-qm/references/slack.md",".codex/skills/deploy-qm/references/email.md",]) {@@ -47,6 +48,7 @@ test("package-consumer deployment skill covers both self-owned providers and the"cli/templates/deployment/SKILL.md","cli/templates/deployment/references/fly.md","cli/templates/deployment/references/aws.md",+ "cli/templates/deployment/references/porter.md","cli/templates/deployment/references/slack.md","cli/templates/deployment/references/email.md",]) {@@ -77,6 +79,27 @@ test("the deploy skill tells an agent where the sign-in email transport comes fr);});+test("the porter reference walks the dashboard steps an agent cannot skip", () => {+ const porter = read("cli/templates/deployment/references/porter.md");+ for (const phrase of [+ "dashboard.porter.run/cloud-accounts",+ "Admin-role",+ "PERMISSION_DENIED",+ "ADMIN_GRANTS",+ "AUTH_ALLOWED_EMAILS",+ "porter apply",+ "linux/amd64",+ ]) {+ assert.ok(porter.includes(phrase), `porter reference covers ${phrase}`);+ }+ assert.match(porter, /operator links one themselves/, "cloud-account linking is called out as the operator's step");+ assert.match(read("cli/templates/deployment/deployment.md"), /references\/porter\.md/);+ assert.match(+ read(".codex/skills/deploy-qm/references/porter.md"),+ /cli\/templates\/deployment\/references\/porter\.md/,+ );+});+test("connector onboarding is governed by the live admin-configured list", () => {const onboarding = read("plugins/onboarding/skills/onboarding/SKILL.md");const connectApps = read("skills-seed/connect-apps/SKILL.md");