# 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 dev` - `artifacts/api-server: API Server` → `pnpm --filter @workspace/api-server run dev` - `artifacts/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) ```javascript // 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: ```bash pnpm install ``` And restart all three workflows (in any order). ## Verification ```bash # 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 # → ... ``` ## Common gotchas - **Port 8080 already in use after a crash loop.** Stale `node ./dist/index.mjs` processes from a previous failed start can hold the port. `ps -ef | grep dist/index.mjs` then `kill -9 ` before restarting the workflow. - **mockup-sandbox transient `Cannot find package 'vite'` on first start.** It's a vite restart race after `pnpm install` invalidates `.vite-temp/`. A second restart of the workflow clears it. - **Do not edit `lib/integrations-*-server/src/client.ts`** if those packages are added later — the env-var wiring is auto-managed. - **`PROXY_API_KEY` is a bearer token, not an OAuth secret.** It only gates `/v1/*`; pick anything. Clients send `Authorization: Bearer `. - **Adding routes to the proxy:** the file is `artifacts/api-server/src/routes/proxy.ts`, mounted at `/v1` in `artifacts/api-server/src/app.ts`. Health/utility routes live under `artifacts/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 ```