Streamproof endpoint deployment — streamproof.aetherin.app
This document prepares the dedicated Vercel project that serves the Streamproof OpenAI-compatible endpoint on top of the shared middleware proxy. It is a runbook: it describes the project/domain/env setup, the routing that makes streamproof.aetherin.app/v1/chat/completions work, how to keep the endpoint private until launch approval, and a smoke test for Continue and Cline.
Do not deploy from this repository as part of a code change. Creating the
project, attaching the domain and lifting Deployment Protection all need
explicit owner approval (see
`aetherin-gtm/launch-checklist.md`
and
streamproof/docs/DEPLOY.md).
What actually runs
The endpoint is the same middleware codebase in this repo, deployed as its own Vercel project. Nothing Streamproof-specific is implemented here; the middleware is a stateless reverse proxy in front of the private core.
Continue / Cline / curl / SDK
│ POST https://streamproof.aetherin.app/v1/chat/completions
▼
Vercel project "streamproof" (this repo)
│ vercel.json rewrite: /v1/:path* → /api/v1/:path*
▼
api/v1/[...path].ts → src/proxy.ts (shared catch-all proxy)
│ drops the leading /api, injects x-service-token
▼
CORE_URL/v1/chat/completions (private; auth enforced by core)Relevant files:
| File | Role |
|---|---|
vercel.json | rewrites map root /v1/* onto the proxy surface; functions grant it a 60s duration for streams |
api/v1/[...path].ts | Thin handler that re-exports the shared proxy |
api/[...path].ts | The catch-all proxy (/api/*) |
src/proxy.ts | Forwarding, auth injection, CORS, size limits, retries, SSE streaming |
.env.streamproof.example | Environment template for the dedicated project |
scripts/smoke-streamproof.sh | Non-stream + stream smoke test |
1. Create the Vercel project
vercel login
cd ~/repos/aetherin-server/aetherin-middleware # or a checkout of the repo
vercel link # "Create a new project" → name it: streamproof- Framework preset: *Other* (the repo is plain TypeScript
api/functions). - Root directory: repository root.
- Build command: leave the default. Vercel compiles the
api/**/*.ts
functions; there is no static build.
- Node version: 20 (matches CI).
- Connect the Git integration so
maindeploys, or deploy manually from CI.
The project is a *second* deployment of the same repo — keep the existing aetherin-middleware project untouched. One repo, two deployments, two sets of env vars.
2. Environment variables
Set these on the streamproof project for Production (and Preview if you want preview smoke tests). Mark CORE_URL and CORE_SERVICE_TOKEN as Sensitive; they are server-side only and must never reach the browser.
| Variable | Example | Purpose |
|---|---|---|
CORE_URL | https://api.aetherin.app | Private base URL of the core runtime. No trailing slash. |
CORE_SERVICE_TOKEN | … | Service-to-service token, forwarded to core as x-service-token. Must match the core's value. |
ALLOWED_ORIGINS | https://streamproof.aetherin.app | Comma-separated browser origins allowed by CORS. |
# Dashboard: Project → Settings → Environment Variables → Add
# Or via the CLI (repeat for each variable):
printf '%s' "$CORE_URL" | vercel env add CORE_URL production
printf '%s' "$CORE_SERVICE_TOKEN" | vercel env add CORE_SERVICE_TOKEN production
printf '%s' "$ALLOWED_ORIGINS" | vercel env add ALLOWED_ORIGINS productionNotes:
ALLOWED_ORIGINSonly affects browser requests. Programmatic clients
(Continue, Cline, curl, SDKs) send no `Origin` header, so they are always accepted. Set the dashboard/portal origin here if it calls the API from a browser.
- Never put
CORE_URLorCORE_SERVICE_TOKENin aNEXT_PUBLIC_*/client
variable. They are intentionally only read in src/config.ts.
3. Custom domain — streamproof.aetherin.app
- Project → Settings → Domains → Add →
streamproof.aetherin.app. - Create the DNS record Vercel shows. For a subdomain this is normally:
| Type | Name | Value |
|---|---|---|
CNAME | streamproof | cname.vercel-dns.com |
If your DNS provider is on Vercel, this is created for you. TLS is issued and renewed automatically.
- Wait for the domain to show Valid Configuration.
aetherin.app (apex) is the Aetherin tools portal; each product gets its own subdomain. Attaching a domain does not make the endpoint public — keep Deployment Protection on (next section).
4. Routing (already configured)
vercel.json does two things for this project:
"rewrites": [
{ "source": "/v1/:path*", "destination": "/api/v1/:path*" }
],
"functions": {
"api/*.ts": { "maxDuration": 10 },
"api/v1/[...path].ts": { "maxDuration": 60 }
}- Root requests to
/v1/chat/completions(and the rest of the OpenAI surface:
/v1/models, …) are rewritten onto /api/v1/…, which is served by the shared catch-all proxy. The proxy strips the leading /api, so the core still sees /v1/chat/completions unchanged.
- The streamproof route gets a 60s
maxDurationso long SSE completions are
not cut off. Raise it (up to your plan's limit) if clients stream for longer.
The existing /api/* surface is unchanged for the other deployment.
5. Keep it private until launch approval ⚠️
The endpoint stays behind Vercel Authentication (Deployment Protection) until public launch is explicitly approved.
- Project → Settings → Deployment Protection → enable **Vercel
Authentication for Production** *and* Preview.
- While enabled, every request — including the custom domain — requires a Vercel
login, so streamproof.aetherin.app is not publicly reachable.
- To automate smoke tests against a protected deployment, create a
Protection Bypass for Automation secret and send it as a header:
curl -H "x-vercel-protection-bypass: $VERCEL_PROTECTION_BYPASS" ...- **Do not disable Deployment Protection without the owner's explicit
approval.** The GTM launch checklist (aetherin-gtm/launch-checklist.md) and streamproof/docs/DEPLOY.md gate public exposure on that approval.
- Rotate any client keys and the automation bypass secret used during testing
before going public.
6. Smoke test
All examples below assume a client key and, while protected, the bypass header:
export STREAMPROOF_BASE=https://streamproof.aetherin.app
export STREAMPROOF_API_KEY=sk-... # a key issued by the core
export VERCEL_PROTECTION_BYPASS=... # only while protected
export BYPASS=(-H "x-vercel-protection-bypass: $VERCEL_PROTECTION_BYPASS")6a. Health
curl -sS "${BYPASS[@]}" "$STREAMPROOF_BASE/api/health"6b. Non-streaming completion
curl -sS "${BYPASS[@]}" "$STREAMPROOF_BASE/v1/chat/completions" \
-H "authorization: Bearer $STREAMPROOF_API_KEY" \
-H 'content-type: application/json' \
-d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"ping"}],"stream":false}'Expect HTTP 200 and an OpenAI-shaped body with choices[0].message.content populated.
6c. Streaming completion
curl -sS -N "${BYPASS[@]}" "$STREAMPROOF_BASE/v1/chat/completions" \
-H "authorization: Bearer $STREAMPROOF_API_KEY" \
-H 'content-type: application/json' \
-H 'accept: text/event-stream' \
-d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"ping"}],"stream":true}'Expect data: SSE chunks and a terminating data: [DONE].
6d. Scripted smoke test
scripts/smoke-streamproof.sh runs 6b and 6c and asserts the shapes:
STREAMPROOF_API_KEY=sk-... npm run smoke:streamproof -- "$STREAMPROOF_BASE"
# or: STREAMPROOF_BASE=... STREAMPROOF_API_KEY=... VERCEL_PROTECTION_BYPASS=... \
# scripts/smoke-streamproof.sh6e. Continue
Add an OpenAI-compatible model to ~/.continue/config.yaml (or config.json for older versions) pointing at the endpoint:
name: aetherin-streamproof
version: 0.0.1
models:
- name: streamproof
provider: openai
model: gpt-4o-mini
apiBase: https://streamproof.aetherin.app/v1
apiKey: ${{ secrets.STREAMPROOF_API_KEY }}
roles:
- chat
- editapiBase must include the /v1 suffix. While Deployment Protection is on, add the bypass header via requestOptions.headers (or run against an unprotected preview).
6f. Cline
In the Cline panel (VS Code):
| Field | Value |
|---|---|
| API Provider | OpenAI Compatible |
| Base URL | https://streamproof.aetherin.app/v1 |
| API Key | your Streamproof client key |
| Model ID | gpt-4o-mini (or another model enabled on the core) |
The base URL includes /v1 (Cline appends /chat/completions). For a protected deployment use a Preview with the request routed through the bypass, or the automation bypass header.
7. Troubleshooting
| Symptom | Likely cause |
|---|---|
403 Origin not allowed | Browser Origin is not in ALLOWED_ORIGINS. Programmatic clients send no Origin and are unaffected. |
401/403 from Vercel (HTML page) | Deployment Protection is on — still expected pre-launch. Send the bypass header. |
502 BAD_GATEWAY / 504 GATEWAY_TIMEOUT | CORE_URL unreachable from Vercel, wrong URL, or request exceeded the timeout. Check core health and the function logs. |
503 SERVICE_UNAVAILABLE | The proxy's circuit breaker tripped after repeated core errors; it resets after ~10s. |
| Stream cut off mid-answer | Function maxDuration too low for the stream; raise api/v1/[...path].ts in vercel.json. |
404 on /v1/... | The rewrites rule is missing or the project deployed from a different commit. |
8. Pre-launch checklist
- [ ] Dedicated Vercel project created and linked to this repo.
- [ ]
CORE_URL,CORE_SERVICE_TOKEN,ALLOWED_ORIGINSset (sensitive) for Production. - [ ]
streamproof.aetherin.appadded and showing Valid Configuration. - [ ] Deployment Protection (Vercel Authentication) on for Production + Preview.
- [ ]
npm run typecheckandnpm testgreen (CI enforces this). - [ ]
scripts/smoke-streamproof.shpasses (with the bypass header while protected). - [ ] Continue and Cline both return real completions against the endpoint.
- [ ] Public launch approved before Deployment Protection is disabled.