feat(openrouter): plumb OPENAI_BASE_URL and OpenRouter headers through installer and compose; docs: add OpenRouter usage

Author: soaringjerry

README.md

@@ -59,7 +59,7 @@ Get PCAS up and running in minutes with our modern development workflow.
 
 - Go 1.24+
 - Docker and Docker Compose
-- An OpenAI API key (for GPT-4 integration)
+- An OpenAI API key (OpenAI or OpenRouter key)
 
 ### 1. Clone and Setup
 
@@ -140,6 +140,10 @@ Prefer a lightweight, interactive flow without Compose?
 - Send a test event: `pcasctl emit --type pcas.test.echo.v1 --data "{\"prompt\":\"hello\"}"`
 - One‑click Docker install/update pulls newest build by default (edge channel). Use `--channel stable` to pin releases.
 
+Using OpenRouter instead of OpenAI:
+- Set env: `OPENAI_BASE_URL=https://openrouter.ai/api/v1` and use an OpenRouter API key in `OPENAI_API_KEY`.
+- Optional headers (recommended by OpenRouter): `OPENROUTER_SITE_URL=https://your.site` and `OPENROUTER_APP_NAME=PCAS`.
+
 ## 🤝 Community & Contribution
 
 PCAS is an open-source project driven by the community. We sincerely invite you to join us.

docker-compose.yml

@@ -30,6 +30,9 @@ services:
       - /app/vendor  # Prevent vendor directory from being overwritten
     environment:
       - OPENAI_API_KEY=${OPENAI_API_KEY:-dummy-key}
+      - OPENAI_BASE_URL=${OPENAI_BASE_URL:-}
+      - OPENROUTER_SITE_URL=${OPENROUTER_SITE_URL:-}
+      - OPENROUTER_APP_NAME=${OPENROUTER_APP_NAME:-}
       - PG_DSN=postgres://pcas:pcas_vector_db@postgres:5432/pcas_vectors?sslmode=disable
       - PCAS_ENV=development
       - GOFLAGS=-mod=readonly -buildvcs=false
@@ -44,4 +47,4 @@ volumes:
 
 networks:
   default:
-    name: pcas-network
+    name: pcas-network

docs/getting-started/installation.md

@@ -16,6 +16,7 @@ Before you begin, ensure you have the following installed:
 -   **Go**: Version 1.24 or later. You can download it from [golang.org](https://golang.org/dl/).
 -   **Docker & Docker Compose**: Required for running PCAS with its default PostgreSQL and ChromaDB dependencies. Follow the official Docker installation guide for your operating system.
 -   **Git**: For cloning the PCAS repository.
+ -   Optional: OpenRouter – if you prefer OpenRouter, set `OPENAI_BASE_URL=https://openrouter.ai/api/v1` and provide your OpenRouter API key in `OPENAI_API_KEY`.
 
 ## Step 1: Clone the PCAS Repository
 
@@ -102,6 +103,7 @@ Options:
 - `-y/--yes` auto-accept prompts (where applicable)
 - `--apply-policy` replace `/data/policy.yaml` inside the running container and restart
 - `--reset-policy` remove existing `/data/policy.yaml` before applying (avoids permission/merge issues)
+ - `--openai-base-url URL` override OpenAI base URL (e.g., `https://openrouter.ai/api/v1`)
 
 What it does:
 - Pulls the image (unless `--no-pull`), ensures a data volume, prepares `policy.yaml`, and runs the container with restart policy.

scripts/install-or-update.sh

@@ -24,6 +24,7 @@ VOLUME="pcas_data"
 POLICY_PATH=""
 POLICY_URL=""
 OPENAI_KEY="${OPENAI_API_KEY:-}"
+OPENAI_BASE_URL="${OPENAI_BASE_URL:-}"
 ADMIN_TOKEN=""
 PULL_IMAGE=1
 START_CONTAINER=1
@@ -54,6 +55,7 @@ Options:
   --policy PATH        Local policy.yaml to mount
   --policy-url URL     Download policy.yaml from URL to --dir/policy.yaml
   --openai-key KEY     Provide OpenAI API key (or set OPENAI_API_KEY env)
+  --openai-base-url URL  Override base URL (e.g., https://openrouter.ai/api/v1)
   --admin-token KEY    Set admin token for dynamic policy updates (PCAS_ADMIN_TOKEN)
   --channel CH         Image channel (default: edge). Use 'stable' for latest release or 'edge' for newest main build
   --update             Force refresh to newest build (edge if available, else latest). Usually unnecessary since default channel=edge
@@ -85,6 +87,7 @@ while [[ $# -gt 0 ]]; do
     --policy) POLICY_PATH="$2"; shift 2 ;;
     --policy-url) POLICY_URL="$2"; shift 2 ;;
     --openai-key) OPENAI_KEY="$2"; shift 2 ;;
+    --openai-base-url) OPENAI_BASE_URL="$2"; shift 2 ;;
     --admin-token) ADMIN_TOKEN="$2"; shift 2 ;;
     --channel) CHANNEL="$2"; shift 2 ;;
     --no-pull) PULL_IMAGE=0; shift ;;
@@ -222,6 +225,7 @@ if [[ ${#ORIG_ARGS[@]} -gt 0 ]]; then
       --policy) POLICY_PATH="$2"; shift 2 ;;
       --policy-url) POLICY_URL="$2"; shift 2 ;;
       --openai-key) OPENAI_KEY=$(sanitize_secret "$2"); shift 2 ;;
+      --openai-base-url) OPENAI_BASE_URL="$2"; shift 2 ;;
       --admin-token) ADMIN_TOKEN=$(sanitize_secret "$2"); shift 2 ;;
       --channel) CHANNEL="$2"; shift 2 ;;
       --no-pull) PULL_IMAGE=0; shift ;;
@@ -344,6 +348,19 @@ else
   warn "OPENAI_API_KEY not provided; search/RAG will be disabled (server still runs)"
 fi
 
+# Optional: custom base URL (e.g., OpenRouter)
+if [[ -n "${OPENAI_BASE_URL}" ]]; then
+  RUN_ARGS+=(-e "OPENAI_BASE_URL=${OPENAI_BASE_URL}")
+fi
+
+# Optional: OpenRouter headers (if provided in env)
+if [[ -n "${OPENROUTER_SITE_URL:-}" ]]; then
+  RUN_ARGS+=(-e "OPENROUTER_SITE_URL=${OPENROUTER_SITE_URL}")
+fi
+if [[ -n "${OPENROUTER_APP_NAME:-}" ]]; then
+  RUN_ARGS+=(-e "OPENROUTER_APP_NAME=${OPENROUTER_APP_NAME}")
+fi
+
 if [[ -n "${ADMIN_TOKEN}" ]]; then
   RUN_ARGS+=(-e "PCAS_ADMIN_TOKEN=${ADMIN_TOKEN}")
 fi