feat: add local LM Studio support, Prometheus metrics, Traefik proxy, and Grafana dashboards

Add Docker infrastructure for local development with LM Studio as LLM provider,
Prometheus metrics collection with custom histograms, Traefik reverse proxy
configuration, and Grafana dashboard provisioning. Update SDK session handling
and deriver queue management for improved reliability.

Author: offendingcommit

.gitignore

@@ -191,3 +191,5 @@ metrics.jsonl
 AGENTS.md
 lancedb_data/
 grafana-data/
+.codex_honcho_runtime/
+.codex_honcho_setup/

CLAUDE.md

@@ -84,6 +84,37 @@ All API routes follow the pattern: `/v1/{resource}/{id}/{action}`
 - Typechecking: `uv run basedpyright`
 - Format code: `uv run ruff format src/`
 
+### Local LM Studio Setup
+
+- Honcho can use LM Studio for generation through the `custom` provider path.
+- Keep `LLM_OPENAI_API_KEY` configured for embeddings unless embedding support is added for local models.
+- For Docker Compose, `LLM_OPENAI_COMPATIBLE_BASE_URL` must be `http://host.docker.internal:1234/v1`, not `http://localhost:1234/v1`.
+- `LLM_OPENAI_COMPATIBLE_API_KEY=lm-studio` is sufficient for local use.
+- Current local default model is `qwen2.5-14b-instruct`.
+- When overriding `DIALECTIC_LEVELS__*` via env vars, each level needs its full required settings, not just `PROVIDER` and `MODEL`. Include `THINKING_BUDGET_TOKENS` and `MAX_TOOL_ITERATIONS`, and optionally `MAX_OUTPUT_TOKENS`.
+- Docker should own the runtime environment completely. Do not mount the repo onto `/app` and do not mount a named volume onto `/app/.venv`, or the image-built environment can be hidden and replaced with incompatible artifacts.
+- If Docker services fail with missing Python modules or incompatible native extensions, rebuild the image instead of trying to repair the environment in-place:
+
+```bash
+docker compose build --no-cache api deriver
+docker compose up -d --force-recreate api deriver
+```
+
+- Verify LM Studio from the host with:
+
+```bash
+curl -sS http://localhost:1234/v1/models
+```
+
+- Verify LM Studio from Docker with:
+
+```bash
+docker compose run --rm --entrypoint sh api -lc 'python - <<\"PY\"
+import urllib.request
+print(urllib.request.urlopen(\"http://host.docker.internal:1234/v1/models\", timeout=5).status)
+PY'
+```
+
 ### SDK Testing
 
 #### TypeScript SDK

Dockerfile

@@ -41,10 +41,13 @@ RUN addgroup --system app && adduser --system --group app && mkdir -p /tmp/uv-ca
 COPY --chown=app:app src/ /app/src/
 COPY --chown=app:app migrations/ /app/migrations/
 COPY --chown=app:app scripts/ /app/scripts/
+COPY --chown=app:app docker/entrypoint.sh /app/docker/entrypoint.sh
 COPY --chown=app:app alembic.ini /app/alembic.ini
 # Copy config files - this will copy config.toml if it exists, and config.toml.example
 COPY --chown=app:app config.toml* /app/
 
+RUN chmod +x /app/docker/entrypoint.sh
+
 # Switch to non-root user
 USER app
 

docker-compose.yml.example

@@ -1,46 +1,65 @@
 services:
+  traefik:
+    image: traefik:v3.2
+    command:
+      - --api.dashboard=true
+      - --api.insecure=true
+      - --providers.file.filename=/etc/traefik/dynamic.yml
+      - --providers.file.watch=true
+      - --entrypoints.web.address=:8000
+      - --ping=true
+    ports:
+      - ${HONCHO_HTTP_PORT:-8000}:8000
+      - ${TRAEFIK_DASHBOARD_PORT:-8080}:8080
+    volumes:
+      - ./docker/traefik/dynamic.yml:/etc/traefik/dynamic.yml:ro
+    networks:
+      - honcho
+
   api:
     image: honcho:latest
     build:
       context: .
       dockerfile: Dockerfile
-    entrypoint: ["sh", "docker/entrypoint.sh"]
+    entrypoint: ["/app/docker/entrypoint.sh"]
     depends_on:
       database:
         condition: service_healthy
       redis:
         condition: service_healthy
-    ports:
-      - 8000:8000
-    volumes:
-      - .:/app
-      - venv:/app/.venv
+      traefik:
+        condition: service_started
+    expose:
+      - 8000
     environment:
       - DB_CONNECTION_URI=postgresql+psycopg://postgres:postgres@database:5432/postgres
       - CACHE_URL=redis://redis:6379/0?suppress=true
     env_file:
       - path: .env
         required: false
+    networks:
+      - honcho
+
   deriver:
     build:
       context: .
       dockerfile: Dockerfile
-    entrypoint: ["/app/.venv/bin/python", "-m", "src.deriver"]
+    entrypoint: ["python", "-m", "src.deriver"]
     depends_on:
       database:
         condition: service_healthy
       redis:
         condition: service_healthy
-    volumes:
-      - .:/app
-      - venv:/app/.venv
     environment:
       - DB_CONNECTION_URI=postgresql+psycopg://postgres:postgres@database:5432/postgres
       - CACHE_URL=redis://redis:6379/0?suppress=true
       - METRICS_ENABLED=true
     env_file:
       - path: .env
         required: false
+    networks:
+      - honcho
+
   database:
     image: pgvector/pgvector:pg15
     restart: always
@@ -56,23 +75,29 @@ services:
     volumes:
       - ./database/init.sql:/docker-entrypoint-initdb.d/init.sql
       - pgdata:/var/lib/postgresql/data/
+    networks:
+      - honcho
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U postgres -d postgres"]
       interval: 5s
       timeout: 5s
       retries: 5
+
   redis:
     image: redis:8.2
     restart: always
     ports:
       - 6379:6379
     volumes:
       - ./redis-data:/data
+    networks:
+      - honcho
     healthcheck:
       test: ["CMD-SHELL", "redis-cli ping"]
       interval: 5s
       timeout: 5s
       retries: 5
+
   prometheus:
     image: prom/prometheus:v3.2.1
     ports:
@@ -83,6 +108,9 @@ services:
     depends_on:
       api:
         condition: service_started
+    networks:
+      - honcho
+
   grafana:
     image: grafana/grafana:11.4.0
     ports:
@@ -98,7 +126,13 @@ services:
     depends_on:
       prometheus:
         condition: service_started
+    networks:
+      - honcho
+
+networks:
+  honcho:
+    name: honcho
+
 volumes:
   pgdata:
-  venv:
   prometheus-data:

docker/entrypoint.sh

@@ -2,7 +2,7 @@
 set -e
 
 echo "Running database migrations..."
-/app/.venv/bin/python scripts/provision_db.py
+python scripts/provision_db.py
 
 echo "Starting API server..."
-exec /app/.venv/bin/fastapi run --host 0.0.0.0 src/main.py
+exec fastapi run --host 0.0.0.0 src/main.py

docker/grafana-dashboards.yml

@@ -0,0 +1,11 @@
+apiVersion: 1
+
+providers:
+  - name: Honcho
+    orgId: 1
+    folder: Honcho
+    type: file
+    disableDeletion: false
+    editable: true
+    options:
+      path: /etc/grafana/provisioning/dashboards/files