Compare commits

..

10 Commits

Author SHA1 Message Date
hwhung da856261f3 Simplify Replit deployment 2026-05-06 00:04:11 +08:00
hwhung 5463862d32 Use Replit default port 2026-04-27 12:43:12 +08:00
hwhung 934ab43ccc Remove config file deployment path 2026-04-27 12:37:02 +08:00
hwhung c5eca5bdb9 Name Replit AI Integrations in setup 2026-04-27 12:34:50 +08:00
hwhung 9a19c87251 Clarify one-shot deployment runbook 2026-04-27 12:29:45 +08:00
hwhung 554ab93df2 Support deployment CLI flags 2026-04-27 12:27:27 +08:00
hwhung 878cd1eb3c Use randomized default port 2026-04-27 12:24:47 +08:00
hwhung 424b691fef Remove old port mention 2026-04-27 12:18:39 +08:00
hwhung 0078ee7e58 Remove pnpm version pin 2026-04-27 12:16:53 +08:00
hwhung bee5dc1e01 Use nonconflicting default port 2026-04-27 12:14:37 +08:00
8 changed files with 183 additions and 153 deletions
+6
View File
@@ -0,0 +1,6 @@
run = "pnpm dev"
onBoot = "pnpm install --ignore-workspace"
[deployment]
build = "pnpm install --ignore-workspace && pnpm run build"
run = "pnpm start"
-23
View File
@@ -1,23 +0,0 @@
{
"server": {
"host": "0.0.0.0",
"port": 8080
},
"proxy": {
"apiKey": "replace-this-token"
},
"providers": {
"openai": {
"apiKey": "internal-openai-token",
"baseURL": "https://your-internal-openai-endpoint/v1"
},
"anthropic": {
"apiKey": "internal-anthropic-token",
"baseURL": "https://your-internal-anthropic-endpoint"
}
},
"logging": {
"level": "info",
"pretty": true
}
}
-1
View File
@@ -3,7 +3,6 @@
"version": "0.0.0",
"license": "MIT",
"type": "module",
"packageManager": "pnpm@10.33.2",
"scripts": {
"dev": "tsx src/index.ts",
"build": "tsc --noEmit && node build.mjs",
+56 -42
View File
@@ -1,64 +1,78 @@
# Agent Runbook
Run this repository as a standalone app. Do not add it to a parent workspace. Do not move it into `artifacts/`. Do not edit source files for setup.
This app is already prepared for one-shot deployment. Follow these commands exactly unless one fails.
## Setup
Do not add this repo to a parent workspace. Do not move it into `artifacts/`. Do not edit source files. Do not edit `package.json`. Do not create `config.json` or a `/tmp` config file for deployment. Do not inspect or free unrelated ports.
## Replit
The repo includes `.replit`, so after import the Run button starts the app with:
```bash
pnpm dev
```
The `.replit` `onBoot` command installs dependencies with:
```bash
pnpm install --ignore-workspace
```
## Install
Run from this repository root:
```bash
pnpm install --ignore-workspace
```
Use the available `pnpm`. This repo intentionally has no `packageManager` pin.
## Start
```bash
pnpm dev
```
If plain `pnpm` is unavailable, use `corepack pnpm` for the same commands. Do not edit `package.json`.
When Replit AI Integrations are provisioned, the app reads these variables automatically:
The app runs without `config.json`:
- `AI_INTEGRATIONS_OPENAI_BASE_URL`
- `AI_INTEGRATIONS_OPENAI_API_KEY`
- `AI_INTEGRATIONS_ANTHROPIC_BASE_URL`
- `AI_INTEGRATIONS_ANTHROPIC_API_KEY`
- host: `0.0.0.0`
- port: `8080`
- bearer token: `dev-proxy-key`
Provider CLI flags are still supported for manual overrides:
## Optional Provider Config
Do not create `config.json` unless internal provider endpoints/tokens are available.
If they are available, create `config.json` in one write with this shape:
```json
{
"server": {
"host": "0.0.0.0",
"port": 8080
},
"proxy": {
"apiKey": "dev-proxy-key"
},
"providers": {
"openai": {
"apiKey": "",
"baseURL": ""
},
"anthropic": {
"apiKey": "",
"baseURL": ""
}
},
"logging": {
"level": "info",
"pretty": true
}
}
```bash
pnpm dev -- \
--openai-base-url "<ai-integrations-openai-base-url>" \
--openai-api-key "<ai-integrations-openai-api-key>" \
--anthropic-base-url "<ai-integrations-anthropic-base-url>" \
--anthropic-api-key "<ai-integrations-anthropic-api-key>"
```
Fill only `providers.openai.apiKey`, `providers.openai.baseURL`, `providers.anthropic.apiKey`, and `providers.anthropic.baseURL`. Use internal endpoints only. Never use public official provider endpoints.
Use Replit AI Integrations endpoints only. Never use public official provider endpoints. Do not print provider tokens.
## Defaults
- host: `0.0.0.0`
- port: `3000`
- bearer token: `dev-proxy-key`
These can be overridden with CLI flags or environment variables:
- `--host` or `HOST`
- `--port` or `PORT`
- `--proxy-api-key` or `PROXY_API_KEY`
## Verify
```bash
curl -s http://localhost:8080/api/healthz
curl -s http://localhost:8080/dashboard | head
curl -s -H "Authorization: Bearer dev-proxy-key" http://localhost:8080/v1/models
curl -s http://localhost:3000/api/healthz
curl -s http://localhost:3000/dashboard | head
curl -s -H "Authorization: Bearer dev-proxy-key" http://localhost:3000/v1/models
```
Expected without provider config: dashboard, health, and model list work; chat completions return `503`.
Expected without provider flags: dashboard, health, and model list work; chat completions return `503`.
Report only the local URL and verification results.
+31 -5
View File
@@ -2,7 +2,7 @@
## Overview
Standalone TypeScript API server with file-based configuration.
Standalone TypeScript API server with Replit run and deployment configuration.
## Stack
@@ -11,20 +11,46 @@ Standalone TypeScript API server with file-based configuration.
- **TypeScript version**: 5.9
- **API framework**: Express 5
- **Build**: esbuild
- **Config**: `config.json` by default, or `--config ./path.json`
## Provider Endpoints
Do not configure this proxy with public official provider endpoints. Agents should populate `providers.openai.baseURL` and `providers.anthropic.baseURL` with the internal endpoints supplied by their runtime/integration, along with the matching internal tokens.
Use Replit AI Integrations endpoints. The app reads these environment variables automatically:
- `AI_INTEGRATIONS_OPENAI_BASE_URL`
- `AI_INTEGRATIONS_OPENAI_API_KEY`
- `AI_INTEGRATIONS_ANTHROPIC_BASE_URL`
- `AI_INTEGRATIONS_ANTHROPIC_API_KEY`
CLI flags are still available for manual overrides:
- `--openai-base-url`
- `--openai-api-key`
- `--anthropic-base-url`
- `--anthropic-api-key`
Never use public official provider endpoints.
## Key Commands
- `pnpm dev` — run API server locally
- `pnpm dev -- --config ./config.local.json` — run with a custom config file
- `pnpm install --ignore-workspace` — install dependencies without joining a parent workspace
- `pnpm dev` — run API server locally on port `3000`
- `pnpm run typecheck` — typecheck the server
- `pnpm run build` — typecheck and build `dist/index.mjs`
- `pnpm start` — run the built server
## Replit Configuration
- `.replit` `run` uses `pnpm dev`
- `.replit` `onBoot` uses `pnpm install --ignore-workspace`
- deployment build uses `pnpm install --ignore-workspace && pnpm run build`
- deployment run uses `pnpm start`
## Server Overrides
- `--host` or `HOST`
- `--port` or `PORT`
- `--proxy-api-key` or `PROXY_API_KEY`
## Routes
- `/` and `/dashboard` — static model dashboard
+34
View File
@@ -0,0 +1,34 @@
Clone and run https://git.komnenos.me/springfw/random-proxy in ./random-proxy.
Goal: get the app running once, with Replit AI Integrations wired, on port 3000.
Do not:
- add it to a parent workspace
- move it into artifacts/
- modify source files
- edit package.json
- create config.json or /tmp config files
- inspect/free unrelated ports
- use nohup/setsid/background shell tricks
- run chat-completion smoke tests unless asked
Steps:
1. Clone into ./random-proxy.
2. Provision/use Replit AI Integrations for:
- OpenAI
- Anthropic
3. Open ./random-proxy and use the configured Replit Run button.
4. Wait briefly, then verify:
curl -s http://localhost:3000/api/healthz
curl -s http://localhost:3000/dashboard | head
curl -s -H "Authorization: Bearer dev-proxy-key" http://localhost:3000/v1/models
Report only:
- local URL
- whether OpenAI and Anthropic AI Integrations were wired
- verification results
+46 -72
View File
@@ -1,6 +1,3 @@
import { existsSync, readFileSync } from "node:fs";
import path from "node:path";
export interface ProviderConfig {
baseURL?: string;
apiKey?: string;
@@ -27,7 +24,7 @@ export interface AppConfig {
const DEFAULT_CONFIG: AppConfig = {
server: {
host: "0.0.0.0",
port: 8080,
port: 3000,
},
proxy: {
apiKey: "dev-proxy-key",
@@ -42,95 +39,72 @@ const DEFAULT_CONFIG: AppConfig = {
},
};
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null && !Array.isArray(value);
function argValue(name: string): string | undefined {
const longName = `--${name}`;
const index = process.argv.findIndex((arg) => arg === longName);
if (index >= 0) {
const value = process.argv[index + 1];
return value && !value.startsWith("--") ? value : undefined;
}
function stringValue(value: unknown): string | undefined {
return typeof value === "string" && value.length > 0 ? value : undefined;
const inlineArg = process.argv.find((arg) => arg.startsWith(`${longName}=`));
return inlineArg ? inlineArg.slice(longName.length + 1) : undefined;
}
function booleanValue(value: unknown): boolean | undefined {
return typeof value === "boolean" ? value : undefined;
function argFlag(name: string): boolean {
return process.argv.includes(`--${name}`);
}
function numberValue(value: unknown): number | undefined {
return typeof value === "number" && Number.isFinite(value) ? value : undefined;
function envValue(name: string): string | undefined {
const value = process.env[name];
return value && value.length > 0 ? value : undefined;
}
function providerConfig(value: unknown): ProviderConfig {
if (!isRecord(value)) return {};
return {
...(stringValue(value["baseURL"]) ? { baseURL: stringValue(value["baseURL"]) } : {}),
...(stringValue(value["apiKey"]) ? { apiKey: stringValue(value["apiKey"]) } : {}),
};
}
function mergeConfig(raw: unknown): AppConfig {
if (!isRecord(raw)) return DEFAULT_CONFIG;
const server = isRecord(raw["server"]) ? raw["server"] : {};
const proxy = isRecord(raw["proxy"]) ? raw["proxy"] : {};
const providers = isRecord(raw["providers"]) ? raw["providers"] : {};
const logging = isRecord(raw["logging"]) ? raw["logging"] : {};
const port = numberValue(server["port"]) ?? DEFAULT_CONFIG.server.port;
function applyArgOverrides(base: AppConfig): AppConfig {
const rawPort = argValue("port") ?? envValue("PORT");
const port = rawPort === undefined ? base.server.port : Number(rawPort);
if (!Number.isInteger(port) || port <= 0) {
throw new Error(`Invalid config value "server.port": ${port}`);
throw new Error(`Invalid port value: ${rawPort}`);
}
const host = argValue("host") ?? envValue("HOST") ?? base.server.host;
const proxyApiKey = argValue("proxy-api-key") ?? envValue("PROXY_API_KEY") ?? base.proxy.apiKey;
const openaiBaseURL = argValue("openai-base-url") ?? envValue("AI_INTEGRATIONS_OPENAI_BASE_URL");
const openaiApiKey = argValue("openai-api-key") ?? envValue("AI_INTEGRATIONS_OPENAI_API_KEY");
const anthropicBaseURL =
argValue("anthropic-base-url") ?? envValue("AI_INTEGRATIONS_ANTHROPIC_BASE_URL");
const anthropicApiKey =
argValue("anthropic-api-key") ?? envValue("AI_INTEGRATIONS_ANTHROPIC_API_KEY");
return {
server: {
host: stringValue(server["host"]) ?? DEFAULT_CONFIG.server.host,
host,
port,
},
proxy: {
apiKey: stringValue(proxy["apiKey"]) ?? DEFAULT_CONFIG.proxy.apiKey,
apiKey: proxyApiKey,
},
providers: {
openai: providerConfig(providers["openai"]),
anthropic: providerConfig(providers["anthropic"]),
openai: {
...base.providers.openai,
...(openaiBaseURL ? { baseURL: openaiBaseURL } : {}),
...(openaiApiKey ? { apiKey: openaiApiKey } : {}),
},
anthropic: {
...base.providers.anthropic,
...(anthropicBaseURL ? { baseURL: anthropicBaseURL } : {}),
...(anthropicApiKey ? { apiKey: anthropicApiKey } : {}),
},
},
logging: {
level: stringValue(logging["level"]) ?? DEFAULT_CONFIG.logging.level,
pretty: booleanValue(logging["pretty"]) ?? DEFAULT_CONFIG.logging.pretty,
level: argValue("log-level") ?? base.logging.level,
pretty: argFlag("pretty-logs")
? true
: argFlag("no-pretty-logs")
? false
: base.logging.pretty,
},
};
}
function configPathFromArgv(): string {
const configArgIndex = process.argv.findIndex((arg) => arg === "--config");
if (configArgIndex >= 0) {
const value = process.argv[configArgIndex + 1];
if (!value) {
throw new Error("Missing value after --config");
}
return path.resolve(value);
}
const inlineArg = process.argv.find((arg) => arg.startsWith("--config="));
if (inlineArg) {
return path.resolve(inlineArg.slice("--config=".length));
}
return path.resolve("config.json");
}
function loadConfig(): AppConfig {
const filePath = configPathFromArgv();
if (!existsSync(filePath)) {
return DEFAULT_CONFIG;
}
let parsed: unknown;
try {
parsed = JSON.parse(readFileSync(filePath, "utf8"));
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
throw new Error(`Could not read config file ${filePath}: ${message}`);
}
return mergeConfig(parsed);
}
export const config = loadConfig();
export const config = applyArgOverrides(DEFAULT_CONFIG);
+1 -1
View File
@@ -494,7 +494,7 @@ function errorMessage(err: unknown): string {
function providerNotConfigured(res: Response, provider: "openai" | "anthropic"): void {
res.status(503).json({
error: {
message: `${provider} provider is not configured. Add providers.${provider}.apiKey and providers.${provider}.baseURL to config.json. Use the internal endpoint supplied by your runtime or agent, not the public provider endpoint.`,
message: `${provider} provider is not configured. Pass the matching Replit AI Integrations CLI flags, not public provider endpoints.`,
type: "server_error",
},
});