开源AI工作流：轻量级多租户Agent路由器

Seed the upstream LLM key (required before the first chat)

The router never reads LLM_BASE_URL / LLM_API_KEY / LLM_MODEL from .env. After logging in as the bootstrap admin:

1. Click the gear icon (lower-left) → Backend API keys. 2. In the LLM_BASE_URL card, set the Global value to your OpenAI-compatible base URL (e.g. https://api.openai.com/v1). 3. In the LLM_API_KEY card, set the Global value to your key. 4. In the LLM_MODEL card, set the Global value to the upstream model id (e.g. gpt-5-mini, qwen3-72b-instruct). This is what hermes / openclaw will pass to the upstream /v1/chat/completions. 5. (Optional) Toggle "Share my Global value with other users" on each card so non-admin users inherit the same value. Without this toggle, every user has to fill their own key in their own settings.

Equivalent REST (admin's own session cookie):

```bash BASE=http://<host>:18000 JAR=/tmp/admin.jar

upgrades are just `git pull && docker compose up -d`.

DATA=$(grep ^HOST_STACK_ROOT .env | cut -d= -f2) sudo mkdir -p "$DATA" && sudo chown $USER "$DATA"

3. Pull the backend images. docker compose only builds router

Docker Hub; `docker pull openclaw/openclaw` would 404).

docker pull ghcr.io/openclaw/openclaw:latest docker pull nousresearch/hermes-agent:latest

Or build the desktop-Chromium overlay shipped in this repo:

cd images/openclaw && docker build -t openclaw-with-chromium:latest .

nanobot has no published image; build it locally from HKUDS PyPI:

docker build -t agstack/nanobot-hkuds:0.1.5.post3 images/nanobot/

4. Build + start router and frontend.

docker compose up -d --build docker compose logs -f agent-stack-router

Option B — build the thin overlay shipped in this repo

If you need OpenClaw's browser plugin to drive a real desktop Chromium, build the overlay and point backends.json at it:

```bash cd images/openclaw docker build -t openclaw-with-chromium:latest .

Uninstall / reset

```bash cd agent-stack docker compose down # stop router + frontend

Quick start

Requirements: Linux host, Docker 24+, ports 18000 (frontend) and 18080 (router) free. The router connects to the local docker.sock to spawn backend containers.

```bash git clone https://github.com/JoursBleu/agent-stack.git cd agent-stack

Sidecar example: backend talks to a same-host LLM proxy

If LLM_BASE_URL points at another container on the same Docker host (e.g. an openai-compat-proxy listening on its own bridge network), the spawned per-user runner needs to be on that network — `network_mode: host` only applies to the router/frontend, not to backend runners.

// backends.json
{
  "name": "openclaw",
  "image": "ghcr.io/openclaw/openclaw:latest",
  "extra_networks": ["my-llm-proxy_default"],
  "extra_env": {
    // resolved by the proxy container's DNS name on that bridge:
    "LLM_BASE_URL": "http://openai-compat-proxy:8080/v1"
  }
}

The router writes a row in the docker network's container table, so inside the runner getent hosts openai-compat-proxy resolves and curl http://openai-compat-proxy:8080/v1/models works. Without extra_networks, every spawned runner lands on the default bridge network and can't reach any sidecar by name (only public DNS endpoints work).

Screenshots

1. Configure .env. The router will refuse to start if JWT_SECRET or

.env. The bootstrap admin saves them in the web UI after first login

3) (optional) share them with non-admin users

curl -s -X PUT -b $JAR -H 'Content-Type: application/json' \ -d '{"shared":true}' $BASE/api/admin/shared-env/LLM_BASE_URL curl -s -X PUT -b $JAR -H 'Content-Type: application/json' \ -d '{"shared":true}' $BASE/api/admin/shared-env/LLM_API_KEY curl -s -X PUT -b $JAR -H 'Content-Type: application/json' \ -d '{"shared":true}' $BASE/api/admin/shared-env/LLM_MODEL ```

Then start a new chat → pick a backend → first message triggers cold start with progress bar; subsequent messages reuse the warm runner.

Option A (default) — use the upstream OpenClaw image as-is

The default image: value already matches; just make sure you ran docker pull (Quick start step 4):

docker pull ghcr.io/openclaw/openclaw:latest

The image lives on GHCR; it is not mirrored to Docker Hub, so docker pull openclaw/openclaw will 404. See openclaw/openclaw for tags and build matrix.

Configuration

`.env`

Upstream LLM credentials (LLM_BASE_URL, LLM_API_KEY, LLM_MODEL) are intentionally not in .env. The bootstrap admin saves them in Settings → Backend API keys on first login (see Quick start above).

Per-user env overrides

• GET /api/me/env-overrides — list (values masked)
• PUT /api/me/env-overrides/{var} — {value}; empty string deletes
• DELETE /api/me/env-overrides/{var}

Recycling a runner after a config change

Changing LLM_BASE_URL / LLM_API_KEY / LLM_MODEL in the UI updates the DB immediately, but the per-user backend container that's already running was started with the old values baked into its rendered seed files. The router only re-renders templated_files on the next ensure() call, and ensure() is a no-op when a runner exists. To force it:

BASE=http://127.0.0.1:18000
curl -s -X DELETE -b $JAR $BASE/api/runners/openclaw       # stop+remove
curl -s -X POST   -b $JAR $BASE/api/runners/openclaw/start # respawn

Or wait for the idle reaper (DEFAULT_IDLE_SECONDS, default 600s).

Optionally drop the router/frontend images too:

docker image rm agent-stack-router:latest agent-stack-frontend:latest ```

Note: router does NOT read LLM_BASE_URL / LLM_API_KEY / LLM_MODEL from

API

All endpoints under /api/* and /v1/* require a session (cookie set by POST /auth/login).

Tuning the upstream model list

The ${LLM_MODEL} placeholder in the seed files only declares one upstream model. To expose more (e.g. let users switch between a fast and a slow model in the OpenClaw UI), edit the seed file directly:

- OpenClaw: seeds/openclaw-home/openclaw.json → add more entries under models.providers.upstream.models[]. - Hermes: seeds/hermes-home/config.yaml has a single ${LLM_MODEL} per sub-component (vision, web_extract, compression, ...); replace any of them with a literal id (or another env placeholder) if you want sub-components on different upstream models.

After editing, git pull && docker compose up -d is enough to push the template into the router container, but already-spawned per-user runners keep their previously rendered seed. Force a re-render by recycling the user's runner (next section).

Backup vs reset

router.db is sqlite + WAL, so the on-disk file is normally accompanied by router.db-wal and router.db-shm containing un-checkpointed transactions. Do not copy router.db alone for backup; either docker compose stop agent-stack-router first, or use:

sqlite3 "$HOST_STACK_ROOT/router.db" ".backup /tmp/router-$(date +%F).db"

For full removal:

Troubleshooting