HTTP Mode

Bobbin can run as an HTTP REST API server for centralized deployments, shared team use, or webhook-driven indexing.

Starting the HTTP Server

bobbin serve --server                  # HTTP on port 3030 (default)
bobbin serve --server --port 8080      # Custom port
bobbin serve --server --mcp            # HTTP + MCP stdio simultaneously

The server binds to 0.0.0.0 on the specified port and includes CORS headers for browser-based clients.

REST API Endpoints

GET /search

curl "http://localhost:3030/search?q=error+handling&limit=5"

GET /grep

curl "http://localhost:3030/grep?pattern=handleAuth&limit=5"

GET /context

curl "http://localhost:3030/context?q=refactor+auth+flow&budget=300"

GET /read

curl "http://localhost:3030/read?file=src/main.rs&start_line=1&end_line=20"

GET /related

curl "http://localhost:3030/related?file=src/auth.rs&limit=5"

GET /refs

curl "http://localhost:3030/refs?symbol=parse_config"

GET /symbols

curl "http://localhost:3030/symbols?file=src/config.rs"

GET /deps

imports and imported_by are omitted, not empty, when a direction was not asked for — so “not asked” stays distinguishable from “none found”.

curl "http://localhost:3030/deps?file=src/config.rs&both=true"

GET /history

Returns the commits plus a stats block: total commits, per-author counts, and churn_rate (commits per 30 days over the returned window). churn_rate is 0.0 when fewer than two commits were returned — one commit gives no interval to measure.

curl "http://localhost:3030/history?file=src/config.rs&limit=10"

GET /hotspots

curl "http://localhost:3030/hotspots?since=6+months+ago&limit=10"

GET /impact

curl "http://localhost:3030/impact?target=src/auth.rs&depth=2"

GET /review

curl "http://localhost:3030/review?diff=staged&budget=300"

GET /similar

curl "http://localhost:3030/similar?target=src/auth.rs:login&limit=5"
curl "http://localhost:3030/similar?scan=true&threshold=0.9"

GET /prime

curl "http://localhost:3030/prime?brief=true"

GET /beads

curl "http://localhost:3030/beads?q=auth+bug&status=open"

GET /status

Returns index statistics in JSON format.

curl http://localhost:3030/status

GET /metrics

Returns Prometheus-compatible metrics.

curl http://localhost:3030/metrics

POST /webhook/push

Triggers re-indexing. Useful for CI/CD pipelines or git webhook integrations. The request must carry Forgejo/Gitea’s X-Gitea-Signature: the lowercase hex HMAC-SHA256 of the exact request body under [archive].webhook_secret.

body='{"ref":"refs/heads/main","repository":{"full_name":"owner/repo"}}'
signature=$(printf %s "$body" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" -hex | awk '{print $2}')
curl -X POST http://localhost:3030/webhook/push \
  -H "X-Gitea-Signature: $signature" -H 'Content-Type: application/json' -d "$body"

Thin-Client Mode

When a remote bobbin server is running, CLI commands can delegate to it instead of accessing local storage:

bobbin search "auth" --server http://localhost:3030
bobbin status --server http://localhost:3030

The --server flag is a global option available on all commands. When set, the CLI acts as a thin client that forwards requests to the HTTP server.

Use Cases

Team Server

Run bobbin on a shared machine with a large codebase indexed once:

# On the server
bobbin init
bobbin index
bobbin serve --server --port 3030

Team members connect via --server flag or configure their AI client to point at the server.

CI/CD Integration

Add a webhook step to your CI pipeline to keep the index fresh:

# After deploy or merge
curl -X POST http://bobbin-server:3030/webhook/push

Combined Mode

Run both HTTP and MCP simultaneously for maximum flexibility:

bobbin serve --server --mcp

This starts the HTTP server on the configured port and the MCP stdio server concurrently. The MCP server handles AI client connections while the HTTP server handles REST API requests and webhooks.