Files
ReplitProxy/readme-setup.md
T
2026-04-27 03:23:03 +08:00

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 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)

// 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.mjs processes from a previous failed start can hold the port. ps -ef | grep dist/index.mjs then kill -9 <pid> 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 <PROXY_API_KEY>.
  • 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