steve
61513aca04
The test assumed webhook events arrive in wall-clock order (queued first, done last), but dispatcher.Fire spawns a goroutine per event with no ordering guarantee. On a single-core CI runner the "queued" goroutine was routinely preempted before making its HTTP POST, letting "loading"/"working"/"done" goroutines land first. Fix: wait until a "done" event appears in the received set (proving all prior transitions have been dispatched by the worker), then assert that "queued" and "done" each appear exactly once rather than checking positional order. Reproduced with: GOMAXPROCS=1 go test -race -count=100 -run TestWebhook_LifecycleEvents ./internal/server/ Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
foreman
A small, always-on Go daemon that fronts one Ollama target. It turns a single Ollama instance into a queued, observable job endpoint: it polls the target's installed models, serializes work through the target (managing model swaps), assigns every job an ID, and reports progress via webhooks.
On the wire it speaks native Ollama, so it doubles as a drop-in go-llm
target.
Quickstart
# Set the required Ollama target URL
export FOREMAN_OLLAMA_URL=http://mac.tail:11434
# Run directly
go run ./cmd/foreman serve
# Or build and run
go build -o foreman ./cmd/foreman
./foreman serve
Docker
docker build -t foreman .
docker run -e FOREMAN_OLLAMA_URL=http://mac.tail:11434 -p 8080:8080 foreman
Configuration
All configuration is via environment variables, namespaced under FOREMAN_*.
See .env.example for the full list.
| Variable | Default | Description |
|---|---|---|
FOREMAN_ADDR |
:8080 |
Listen address |
FOREMAN_OLLAMA_URL |
(required) | Ollama target base URL |
FOREMAN_OLLAMA_TOKEN |
(empty) | Bearer token sent to the target |
FOREMAN_TOKEN |
(empty) | Bearer token callers must present |
FOREMAN_EMBED_MODEL |
(empty) | Always-resident embedder model |
FOREMAN_DB_PATH |
foreman.db |
SQLite database path |
FOREMAN_POLL_INTERVAL |
30s |
Target model poll interval |
FOREMAN_WEBHOOK_SECRET |
(empty) | HMAC key for webhook signing |
Health check
curl http://localhost:8080/healthz
# {"status":"ok","degraded":false}
Architecture
See docs/adr/ for design decisions. Key points:
- One daemon per Ollama target (ADR-0001)
- SQLite-backed durable job queue in WAL mode (ADR-0008)
- Single worker loop with drain-by-model scheduling (ADR-0009)
- Native Ollama passthrough + async
/jobssurface (ADR-0003, ADR-0004) - Embeddings bypass the queue entirely (ADR-0013)