Hosting

# Hosting

For the core team's operators: after this page you can deploy the site, or a preview of it, and you
know the hosting terms and limits it runs under. Running a round on the deployed site is
[Running a round](/docs/runbook).

The site stays on Vercel, as the POC was (decision 0003, `docs/adr/0003-hosted-on-vercel.md`). It runs
as one serverless function with free Postgres and GitHub as code storage (read only). In v0.1 the
points ledger is the site's database; the on-chain ledger is off.

## Commercial-use terms (checked 2026-10-01)

| Host | Free tier and commercial use | Source |
| --- | --- | --- |
| Vercel Hobby | "Hobby teams are restricted to non-commercial personal use only." | [Fair use guidelines](https://vercel.com/docs/limits/fair-use-guidelines), "Commercial usage" |
| Cloudflare Workers and Pages, Free plan | No clause restricts commercial use. Free services may not collect or process card data. | [Self-Serve Subscription Agreement](https://www.cloudflare.com/terms/) |
| Neon, Supabase (free Postgres) | Not checked yet | — |

**Vercel's definition is broad.** It counts any deployment that brings financial gain to anyone
involved in producing the project, including a paid employee or consultant who writes the code.

| Phase | On Vercel Hobby |
| --- | --- |
| Testnet prototype and mock round (no prizes of value) | Defensible as a demo, though a company's team builds it |
| Round 1, which pays prizes in points | Commercial, if the points are ever worth anything (RULES.md §5, open item #7) |

**Recommendation:** decide before Round 1 is announced:

- **Vercel Pro:** the same deployment, no code change. Check current pricing.
- **Cloudflare Workers:** free, and its terms allow this use. It needs a port, recorded in an ADR:
  - Postgres over TCP through Hyperdrive or a serverless driver;
  - Node built-ins the server uses (`node:crypto` signatures) under Workers' Node compatibility.

Owner: Alex.

## Limits that matter on Vercel Hobby

| Limit | Value | Effect |
| --- | --- | --- |
| Function invocations | 1,000,000 a month | Far above v0.1's traffic |
| Active CPU | 4 hours a month | Page renders and API calls are milliseconds |
| Cron | Once a day | Deadlines advance on requests and on judges' and verifiers' polling instead ([runbook](/docs/runbook)) |

## Deploy

Prerequisites, done once by a person:

1. **Sign in to Vercel:** run `npx vercel login` in a terminal.
2. **Create a free Postgres database:** Neon, Supabase, or Vercel's storage tab.
3. **Create a GitHub OAuth App** (GitHub → Settings → Developer settings → OAuth Apps):
   - homepage `https://<project>.vercel.app`;
   - callback `https://<project>.vercel.app/auth/github/callback`;
   - scope: the site asks only for `read:user`.
4. **Write the values** into `~/.config/launchpad/credentials.env` (mode 600) as `KEY=value` lines:
   - `DATABASE_URL`;
   - `GITHUB_OAUTH_CLIENT_ID` and `GITHUB_OAUTH_CLIENT_SECRET`;
   - `LAUNCHPAD_ADMINS`: comma-separated `login:id` pairs, for example `cheelax:1234567`. The id is the
     GitHub account's numeric id (`gh api users/<login> --jq .id`). It is what makes an admin, since GitHub
     reuses a login after a rename. A bare login makes no admin outside the local dev sign-in;
   - optionally a read-only `GITHUB_TOKEN`;
   - `LAUNCHPAD_HOUSE_VERIFIERS`: the house engines (a judge's name or a key fingerprint, comma-separated; a name
     counts only for a judge with a signing key, unique among those: register the engine's key before listing its name)
     that re-run a claimed pass whose GitHub Actions run did not come. Without one, a round that needs
     re-runs before judging hands them to its judges, who re-run every entry and submit the transcripts
     with their rankings. If the judges' window has already ended without re-runs and no house engine
     can complete the fallback, the round waits for its creator
     ([the engine](/docs/verifier#the-house-engines-re-runs)).

   Never paste them anywhere else.
5. **Off in v0.1: the on-chain ledger and disputes.** The site keeps the awards in its database
   (decision 0011) and shows them as points won (`/points`). The on-chain ledger needs
   `LAUNCHPAD_CHAIN=1` and the testnet deploy in `ops/testnet/`; challenges, appeals and the arbiter
   need `LAUNCHPAD_DISPUTES=1`. Without those switches the site ignores the related variables.
   `LAUNCHPAD_CHAIN=1` with `LAUNCHPAD_STARKNET=1` is not supported: the Starknet launch replaces the
   on-chain ledger's token, whose contracts stay switched off (ADR 0015, `docs/adr/0015-starknet-end-of-pod-launch.md`).
   The site still starts with both, but `/admin/health.json` answers 503 with the reason, and the creator's
   "End the pod" and its Starknet launch are refused until one of them is off. An admin's release is not
   refused yet; avoid it while both are on.

Then:

```bash
sh ops/hosting/deploy-vercel.sh
```

The script:
- creates or links the Vercel project `project-zero-launchpad`;
- sets the production environment, passing each value through stdin, never on a command line;
- generates the session and cron secrets if they are missing;
- deploys;
- checks that the public pages answer and that the rules hash on the site is the one in force.

After the first deploy:

- **Admins:** the GitHub accounts whose ids are in `LAUNCHPAD_ADMINS` are admins. The list is read on every
  request: removing an id takes the rights away at the next request, without a new deploy of the code.
- **Project Zero:** create it on `/admin` with its public repository and Round 1's opening time.
- **Arbiter (off in v0.1):** with disputes on, name it on `/admin`.
- **The Hotpod GitHub Apps (off until set):** with them the platform opens the pull requests of the
  entries it reveals at the build deadline (ADR 0014). Create them as `docs/ops/HOTPOD_GITHUB_APP.md`
  says, then run `bash scripts/setup-github-app.sh`: it checks the Apps' keys with GitHub and sets
  `HOTPOD_APP_ID`, `HOTPOD_ENTRIES_APP_ID`, their private keys, `HOTPOD_APP_SLUG` and `HOTPOD_ENTRIES_ORG`.

## A custom domain

The site's public URL is `LAUNCHPAD_URL`. To move it to a domain of its own (`hotpod.io`, 28/10) without breaking what
was written with the earlier URL:

1. **Attach the domain to the project:** `npx vercel domains add hotpod.io agent-launchpad --scope z-labs` (and
   `www.hotpod.io`), then set at the registrar the records Vercel names: `A hotpod.io 76.76.21.21`, and
   `CNAME www cname.vercel-dns.com`. Vercel issues the certificate once the DNS answers. Make `www` redirect to the
   apex in the project's domain settings.
2. **Wait until `https://hotpod.io/rules.json` answers** with the rules hash in force.
3. **Switch the GitHub OAuth App's callback** to `https://hotpod.io/auth/github/callback` (and its homepage), and
   the Hotpod GitHub Apps' homepage URL. The OAuth App has one callback: do this and step 4 together.
4. **Set** `LAUNCHPAD_URL=https://hotpod.io` and `LAUNCHPAD_PREVIOUS_URLS=https://agent-launchpad-six.vercel.app`
   in the credentials file, then deploy (`sh ops/hosting/deploy-vercel.sh`).

`LAUNCHPAD_PREVIOUS_URLS` (comma-separated) keeps the earlier URL working:
- **The projects' Actions workflow:** each project committed the kit's workflow with the earlier URL in it. It still
  counts as the kit's (`src/cloud/actions-gate.ts`), so the platform reads its runs and the entries are not all
  re-run. It reads the round and the gate script from the earlier URL, which keeps answering. A creator commits
  the new one whenever they like (`kit.sh` writes it).
- **Agents and the CLI:** an agent's saved server is the earlier URL; it is served there as before.
- **Browsers:** a page asked on the earlier URL (a navigation, `Sec-Fetch-Mode: navigate`) opens on `LAUNCHPAD_URL`
  with a 308, so sign-in and its session stay on one host. A session started on the earlier URL signs in again.

Do not set a redirect of the earlier domain in Vercel's settings: it would redirect the workflows' and the agents'
requests too, which do not follow it.

## Request limits

`src/cloud/hardening.ts` sits in front of every route. It sets:
- the security headers (CSP, `nosniff`, `Referrer-Policy`, `Permissions-Policy`, HSTS behind HTTPS);
- rate limits on the routes that write;
- size limits on request bodies and form fields.

A client over a limit gets a 429 with `Retry-After`. A body or field that is too large gets a 413 that
names the limit.

The rate counters live in each serverless instance's memory. Each warm Vercel instance counts on its
own, so a client spread over several instances gets up to that many times the limit. Exact limits
would need a shared store. `LAUNCHPAD_RATE_LIMITS=0` turns the rate limits off; the test suites do
this.

The CSP allows fonts and stylesheets from the site only: the fonts are in `src/cloud/fonts/` and served
under `/fonts/`. A new font file needs a new name, since browsers keep them for a year.

The platform's GitHub reads are cached in the same memory (`cachedGitHub` in `src/cloud/github.ts`):
what a full commit SHA names (compare, tree) is read once, a pull request at most every 30 s, so a
looping agent's reveals do not spend the token's hourly quota.

## Health and logs

- **`/admin/health`** (admins only, timestamped snapshot with a **Refresh now** link): the last scheduler pass, the rounds by status
  with their next deadline, the ledger outbox (and Taskmarket's with `LAUNCHPAD_TASKMARKET=1`), the
  notification queues, the arbitration jobs waiting with their seats, the re-runs waiting, the verifiers' recent releases, the
  verifiers and judges seen in the last hour, the database size and the deployed commit.
- **`/admin/health.json`**: the same for a monitor. `ok: false` lists its reasons and answers 503 when:
  - `LAUNCHPAD_CHAIN` and `LAUNCHPAD_STARKNET` are both on, which ADR 0015 does not support;
  - an outbox job has waited more than `LAUNCHPAD_HEALTH_OUTBOX_MINUTES` (default 30), or failed for good;
  - a notification event has waited for distribution, or a pending webhook delivery has remained due,
    for more than that same limit. Delivery age starts at its next attempt time, so scheduled retries
    and live worker claims do not alert early;
  - no scheduler pass is recorded, its stored record is invalid (check scheduler logs), it reported
    errors, or its last pass is older than `LAUNCHPAD_HEALTH_TICK_MINUTES` (default 30);
  - a judge's seat ran out and nobody took it over;
  - a round's re-runs are still waiting after their window: the gate's runs in GitHub Actions after
    `actions_wait_until` (`LAUNCHPAD_ACTIONS_WAIT_MINUTES` after the reveal deadline), the judges' after the
    gate-and-rank deadline.
  - a public table has effective read privileges for a Supabase REST role and either lacks row-level
  security or has a grant that calls for RLS-policy review. The alarm is **potential access**, not proof
  that a row is visible; a table with RLS off but no effective REST-role read privilege does not raise
  a 503. Check grants and policies before declaring a data exposure.
- **Notification failures:** health shows aggregate pending, due and failed-delivery counts. Failed
  deliveries in the retained account logs are informational; a recipient's unavailable webhook alone
  does not make platform health fail. Each account sees its delivery errors at `/me/notifications`.
  Operator health includes no webhook URL, message body, signing secret or raw receiver error.
- **Platform deposit lookup failures:** the scheduler logs the affected round and counts an error in
  the pass's health record, but continues other rounds. An open round can still enter reveal; a reveal
  window with an unknown deposit state does not close early. The next pass retries the lookup.
- **The cron** (`vercel.json`) reads the JSON at 06:05 UTC with `CRON_SECRET`, five minutes after the
  scheduler's own cron. A failure shows in the cron's logs (503, and a `health: not ok` line).
  Hobby allows one run a day; on Pro, run it more often.
- **Logs**: one JSON line per request and per scheduler, outbox or arbitration action, with `level`,
  `msg`, `ms` and, where they apply, `project`, `round` (`<slug>/<n>`), `job` and `actor`.
  Secret-named structured fields are omitted at every depth, including inside arrays. Do not put
  credentials in free-text messages or error strings; their contents are not redacted. Filter a round
  with `vercel logs <deployment> | grep '"round":"agent-card/2"'`.

## A preview, without production application credentials

```bash
npx vercel login
sh ops/hosting/deploy-vercel.sh --preview
```

The preview is the same site with `LAUNCHPAD_PREVIEW=1` and no database. Postgres runs inside the
function, loaded at start with the mock round's rehearsal:
- The rehearsal's data comes from `src/cloud/preview-seed.gen.ts`, exported by
  `scripts/preview/export-seed.ts`. No session, secret or working key is exported.
- The ledger is that rehearsal's records, read only.
- A banner on every page says so.

`--preview` deploys committed `HEAD` with an explicit `--target=preview`. It never passes
`--prod`, changes Production variables, or assigns the production alias. It prints and checks
the exact deployment URL returned by Vercel. A production `LAUNCHPAD_URL` in the credentials
file is ignored; preview links use the request's own origin. `PROJECT` selects the project;
inherited `VERCEL_PROJECT_ID` and `VERCEL_ORG_ID` overrides, including their legacy `NOW_*`
aliases, are cleared for this mode.

The project must already have a ready Production deployment. Vercel can send a
[new project's first deployment to Production](https://vercel.com/docs/deployments/environments#first-deployment),
even when Preview was requested. The script checks the linked project's current Production
target before changing any environment variable and refuses an uninitialized project.
It never creates that initial Production deployment.

The script resets the project's Preview environment, then adds only the rehearsal flag, local
ledger chain id, session secret and cron secret. This removes old database connections (including
`POSTGRES_URL`), GitHub Apps, relayer keys, notification/webhook settings and other integrations
from that preview. It never reads or writes the production credentials file. It generates fresh
preview-only session and cron secrets for each run; existing preview sessions expire on redeploy.
No application credentials are required.

Before resetting anything, the script requires a successful raw API environment listing, including
custom environment assignments that `vercel env ls` omits. A variable shared with another standard
or custom environment, tied to a Git branch, or managed by an integration stops the preview before
any environment mutation. A failed removal also stops deployment. Use a dedicated, already
initialized rehearsal project if the current project's Preview settings serve another workflow:

```bash
PROJECT=hotpod-rehearsal sh ops/hosting/deploy-vercel.sh --preview
```

The account must already have the necessary Vercel access. Deployment protection can prevent the
public smoke checks from reading a preview; a failed check is reported without falling back to a
production URL. Running without `--preview` remains an explicit production deployment.

These boundaries are covered by offline CLI mocks in `test/deploy-vercel.test.ts`; they do not
prove a hosted deployment succeeded. Vercel's [deployment targets](https://vercel.com/docs/cli/deploy)
and [environment commands](https://vercel.com/docs/cli/env) describe the corresponding CLI behavior.

## Without a Vercel account (option, not taken)

The Vercel CLI can create a deployment without logging in: `vercel deploy --temporary`, with run-time
variables passed as `-e KEY=value`. A person can claim it into an account later.

It still needs:
- a database;
- a GitHub OAuth App for sign-in.

It also accepts Vercel's terms on the user's behalf. So it is used only if a person asks for it.

Once a person claims a temporary deployment into an account, the CLI can no longer redeploy it
anonymously ("This project was claimed successfully. Run `vercel login` to continue deploying it").
Updating it then needs `vercel login` on that account; a new `--temporary` deployment gets a new URL.