5.2 KiB
Setup Guide (for future Replit Agents)
A short, copy-paste-friendly checklist to get this project running from a clean clone. Read this before restarting workflows or asking the user for credentials.
What this project is
A pnpm monorepo with three artifacts:
| Artifact | Path | Port | Purpose |
|---|---|---|---|
api-server |
artifacts/api-server |
8080 |
Express server. /api/* (health) + /v1/* OpenAI-compatible reverse proxy in front of OpenAI and Anthropic. |
api-portal |
artifacts/api-portal |
24927 |
React + Vite frontend that shows connection info and CherryStudio setup. |
mockup-sandbox |
artifacts/mockup-sandbox |
8081 |
Vite dev server for component previews. |
The proxy exposes GET /v1/models and POST /v1/chat/completions. Model variants are auto-generated by suffixing the base id with a reasoning effort, e.g. gpt-5.2-low, claude-opus-4-6-high. For Anthropic models the suffix maps to thinking.budget_tokens.
Workflows (already configured in .replit-artifact/artifact.toml per artifact)
artifacts/api-portal: web→pnpm --filter @workspace/api-portal run devartifacts/api-server: API Server→pnpm --filter @workspace/api-server run devartifacts/mockup-sandbox: Component Preview Server→pnpm --filter @workspace/mockup-sandbox run dev
Do not edit artifact.toml directly — use the artifacts skill helpers (createArtifact, verifyAndReplaceArtifactToml).
Required env vars / secrets
The api-server instantiates the OpenAI and Anthropic SDKs at import time. If any of these are missing it crashes immediately on startup with OpenAIError: Missing credentials or similar.
| Name | How to set | Notes |
|---|---|---|
AI_INTEGRATIONS_OPENAI_BASE_URL |
setupReplitAIIntegrations({ providerSlug: "openai", ... }) |
auto-set |
AI_INTEGRATIONS_OPENAI_API_KEY |
same call | auto-set (dummy string for SDK; works alongside BASE_URL) |
AI_INTEGRATIONS_ANTHROPIC_BASE_URL |
setupReplitAIIntegrations({ providerSlug: "anthropic", ... }) |
auto-set |
AI_INTEGRATIONS_ANTHROPIC_API_KEY |
same call | auto-set |
PROXY_API_KEY |
requestEnvVar({ requestType: "secret", keys: ["PROXY_API_KEY"] }) |
user-defined; bearer token clients send |
One-shot setup script (in the JS sandbox)
// 1. Provision OpenAI + Anthropic via Replit AI Integrations
await setupReplitAIIntegrations({
providerSlug: "openai",
providerUrlEnvVarName: "AI_INTEGRATIONS_OPENAI_BASE_URL",
providerApiKeyEnvVarName: "AI_INTEGRATIONS_OPENAI_API_KEY",
});
await setupReplitAIIntegrations({
providerSlug: "anthropic",
providerUrlEnvVarName: "AI_INTEGRATIONS_ANTHROPIC_BASE_URL",
providerApiKeyEnvVarName: "AI_INTEGRATIONS_ANTHROPIC_API_KEY",
});
// 2. Ask the user for their proxy bearer token (suggest a random one)
const crypto = await import("node:crypto");
const suggested = crypto.randomBytes(24).toString("base64url");
await requestEnvVar({
requestType: "secret",
keys: ["PROXY_API_KEY"],
userMessage: `Bearer token for /v1/* on the proxy. Suggested: ${suggested}`,
});
Then in the shell:
pnpm install
And restart all three workflows (in any order).
Verification
# health
curl -s http://localhost:8080/api/healthz
# → {"status":"ok"}
# auth gate
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/v1/models
# → 401
# model list (replace with your secret)
curl -s -H "Authorization: Bearer $PROXY_API_KEY" http://localhost:8080/v1/models | head -c 200
# portal
curl -s http://localhost:24927/ | head -c 80
# → <!DOCTYPE html> ...
Common gotchas
- Port 8080 already in use after a crash loop. Stale
node ./dist/index.mjsprocesses from a previous failed start can hold the port.ps -ef | grep dist/index.mjsthenkill -9 <pid>before restarting the workflow. - mockup-sandbox transient
Cannot find package 'vite'on first start. It's a vite restart race afterpnpm installinvalidates.vite-temp/. A second restart of the workflow clears it. - Do not edit
lib/integrations-*-server/src/client.tsif those packages are added later — the env-var wiring is auto-managed. PROXY_API_KEYis a bearer token, not an OAuth secret. It only gates/v1/*; pick anything. Clients sendAuthorization: Bearer <PROXY_API_KEY>.- Adding routes to the proxy: the file is
artifacts/api-server/src/routes/proxy.ts, mounted at/v1inartifacts/api-server/src/app.ts. Health/utility routes live underartifacts/api-server/src/routes/and are mounted at/api.
File map (key paths)
artifacts/
api-server/
src/app.ts # express setup, mounts /api and /v1
src/routes/proxy.ts # /v1/models + /v1/chat/completions, OpenAI+Anthropic
src/routes/health.ts # /api/healthz
build.mjs # esbuild bundler
api-portal/
src/App.tsx # connection info + CherryStudio instructions
vite.config.ts
mockup-sandbox/
vite.config.ts
lib/
api-spec/openapi.yaml # OpenAPI source for codegen
api-zod/ # generated zod schemas
api-client-react/ # generated react-query hooks
db/ # drizzle schema (unused by the proxy itself)
replit.md # high-level project overview