Vercel setup
Everything the Aetherin frontend, API edge and API reference need on Vercel, and how to verify it. All of it is on the free (Hobby) tier — no card, no spend.
The token lives in two places, and they must agree:
| Where | Why |
|---|---|
~/.env → VERCEL_TOKEN | the local operator session |
Infisical → *Streamproof (LIVE)* → prod | CI and the deploy scripts |
They were out of sync once (the Infisical copy was rejected by the API). Check yours with:
curl -sS -o /dev/null -w '%{http_code}\n' \
-H "Authorization: Bearer $VERCEL_TOKEN" https://api.vercel.com/v2/user
# 200 = fine, 403 = the token is invalid againThe three projects
| Project | Domain | What it serves | Source repo |
|---|---|---|---|
aetherin-middleware | api.aetherin.app | the public API edge (Vercel Functions) | aetherin-middleware |
aetherin-frontend | app.aetherin.app | the dashboard / console (Next.js) | aetherin-frontend |
aetherin-api-docs | docs.aetherin.app | the API reference, built from the contract | aetherin-common |
The apex aetherin.app still belongs to aetherin-portal — the cutover is a decision, not a configuration. admin.aetherin.app belongs to admin-console (a separate operations console, not this one).
Settings that are set on every project
| Setting | Value | Why |
|---|---|---|
| Git integration | linked to the source repo, branch main | a push deploys by itself |
createDeployments | enabled | auto-deploy on push (it was disabled — nothing deployed automatically) |
serverlessFunctionRegion | `fra1` (Frankfurt) | EU data residency and the lowest latency to the core in Germany; it was iad1 (US East) |
ssoProtection.deploymentType | all_except_custom_domains | previews stay private, the public domains do not |
autoExposeSystemEnvs | false | do not leak VERCEL_* into the functions |
autoAssignCustomDomains | false | a new hostname is never silently stolen by a project |
framework | nextjs (frontend), none (middleware, docs) | the frontend must be detected as Next.js or it builds nothing and every route 404s |
outputDirectory | docs-site/dist (docs) | the docs site is a static build |
buildCommand | node docs-site/build.mjs (docs) | builds the reference from the contract |
Environment
| Project | Variable | Value |
|---|---|---|
| middleware | CORE_URL | https://gateway.aetherin.app/aether/gateway |
| middleware | CORE_SERVICE_TOKEN | shared with the core (the deploy .env) |
| middleware | ALLOWED_ORIGINS | the browser origins that may call the API |
| middleware | REQUIRE_AUTH | true — the edge gate |
| middleware | CRON_SECRET | protects the cron endpoint (also in Infisical) |
| frontend | NEXT_PUBLIC_API_BASE | https://api.aetherin.app (no /v1 — the client adds it) |
| docs | — | none |
The free extras that are switched on
- Vercel Analytics (frontend) — cookie-less aggregate usage.
- Speed Insights (frontend) — Core Web Vitals.
- A daily cron (middleware) —
0 6 * * *calls/api/cron/health, which
probes the core and reports latency and reachability. A failed cron shows up in the project's cron log, so a dead upstream is visible in Vercel instead of only being discovered by a customer.
- A metrics cron (middleware) —
0 */4 * * *calls/api/cron/metrics,
which scrapes the core's /metrics with the service token and reports the result. The core's counter and latency histogram are what the alert rules read.
- Redirects and edge headers —
/health,/healthz,/readyz,/version
and /metrics point at their canonical paths, and every response carries the hardening headers. The console's CSP derives its connect-src from NEXT_PUBLIC_API_BASE, so a staging deployment is not blocked by a hardcoded host.
- Preview deployments are protected with Vercel Authentication, so a preview
URL is not a public URL.
What is deliberately not enabled (and why)
- The AI Gateway — free with your own keys, but our core already does
provider selection and fallback for 20+ providers. Adding the gateway as a second routing layer would mean two places deciding where a request goes.
- Firewall rules / WAF (rate limiting, custom rules) — Pro-only on the free
tier. The edge has its own auth gate, request-size limits and circuit breaker instead.
- Vercel Postgres / Vercel KV — both have free tiers, but the core speaks
the Postgres and Redis *wire protocols*; these are HTTP APIs, so the client libraries cannot use them without a rewrite. The core keeps its own Postgres and Redis.
- The credits-based AI Gateway / Observability paid tiers — they need a
card, and the free tier covers what we use.
Operating it
# redeploy one project
cd aetherin-middleware && npx vercel deploy --prod --yes
cd aetherin-frontend && npx vercel deploy --prod --yes
cd aetherin-common && npx vercel deploy --prod --yes # the docs site
# point a domain at the newest build (a deploy does not always move it)
npx vercel alias set <deployment-url> api.aetherin.app
# what is live right now
curl -sSk https://api.aetherin.app/api/health # 502 until the core is up
curl -sSk https://app.aetherin.app/ # the dashboard
curl -sSk https://docs.aetherin.app/ # the API referenceThe one thing that is still missing
api.aetherin.app answers 502 Bad Gateway — the edge is healthy, its upstream is not. The core is not deployed on the gateway host yet. That is the last blocker, and it is not a Vercel problem:
# on the gateway host
cd /opt/aetherin-stack && bash scripts/apply-edge.shSee `launch-blockers.md` (./launch-blockers.md) for the whole list.