118 lines
5.2 KiB
Markdown
118 lines
5.2 KiB
Markdown
# 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
|
|
# → <!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
|
|
```
|