Team Deployment¶

The typical setup: one KB instance runs on a shared server with your org's sources ingested. Developers and AI agents connect to it from their own machines via CLI, HTTP, or MCP.

Server setup¶

1. Install¶

On the server:

curl -fsSL https://knowledgebroker.dev/install.sh | sh

2. Ingest your org's sources¶

kb ingest --git https://github.com/acme/platform --description "Platform services"
kb ingest --confluence ENGINEERING --description "Engineering wiki"
kb ingest --slack C0ABC123DEF --description "Platform engineering channel"

Set up a cron job or CI step to re-run ingestion periodically. Only new or changed files are processed.

3. Configure synthesis (optional)¶

Set an API key on the server for answer synthesis. Without one, raw retrieval still works.

The recommended approach for servers is a config file:

# Create a server config file
cat > /etc/kb/config <<EOF
ANTHROPIC_API_KEY=sk-ant-...
KB_LISTEN_ADDR=:8080
EOF

Or use environment variables directly (standard for containers):

export ANTHROPIC_API_KEY=sk-ant-...

4. Start the server¶

# With config file
kb serve --config /etc/kb/config

# Or with env vars
kb serve

This starts three things in one process:

Transport	Address	Purpose
HTTP API	`:8080`	REST queries, ingestion, source management
MCP SSE	`:8082`	Remote MCP clients
MCP stdio	—	Local MCP clients (subprocess)

Customize ports with --addr and --mcp-addr. For a headless deployment with no stdio:

kb serve --no-stdio

Connecting from developer machines¶

Developers don't need to run their own KB instance. They connect to the shared server.

CLI with --remote¶

Install kb locally, then point any command at the server:

# Query
kb query --remote http://server:8080 "how does auth work?"
kb query --remote http://server:8080 --raw "retry logic"

# List sources
kb sources list --remote http://server:8080

# Push a local repo to the shared instance
kb ingest --source ./my-repo --remote http://server:8080

# Export
kb export --remote http://server:8080 --out ./export/

Every CLI command accepts --remote. When set, it talks to the server over HTTP instead of using a local database.

MCP clients (Claude Code, Cursor, Windsurf)¶

Point MCP clients at the server's SSE endpoint. No local kb binary required.

For Claude Code, add to .mcp.json:

{
  "mcpServers": {
    "knowledge-broker": {
      "type": "sse",
      "url": "http://server:8082/sse"
    }
  }
}

Every developer's agent queries the same shared knowledge base. No local install, no local database. Add a prompt to your project config so agents use KB automatically -- see Agent prompts.

HTTP API¶

Query the server directly from scripts, CI, or custom integrations:

# Synthesised answer
curl -s -X POST http://server:8080/v1/query \
  -H 'Content-Type: application/json' \
  -d '{"messages":[{"role":"user","content":"how does auth work?"}]}'

# Raw retrieval
curl -s -X POST http://server:8080/v1/query \
  -H 'Content-Type: application/json' \
  -d '{"messages":[{"role":"user","content":"how does auth work?"}],"mode":"raw"}'

# List sources
curl -s http://server:8080/v1/sources

# Health check
curl -s http://server:8080/v1/health

See CLI Reference for the full API.

Keeping the knowledge base fresh¶

Cron¶

Re-ingest all registered sources on a schedule:

# Every hour
0 * * * * /usr/local/bin/kb ingest --all

CI/CD¶

Add ingestion to your deploy pipeline so the knowledge base updates whenever docs or code ship:

# In your CI job
kb ingest --source . --remote http://kb-server:8080 --description "My service"

Developer contributions¶

Any developer can push their local repo to the shared instance:

kb ingest --source ./my-project --remote http://server:8080 --description "Payment service"

Monitoring¶

The HTTP server exposes a /metrics endpoint for Prometheus scraping. Use it with Prometheus + Grafana for dashboards and alerting.

curl http://server:8080/metrics

Available metrics include HTTP request counts and latency (kb_http_requests_total, kb_http_request_duration_seconds), query counts by mode (kb_queries_total), query latency by phase (kb_query_duration_seconds), and query errors (kb_query_errors_total).

Network and security¶

KB does not include authentication. For production deployments:

Run behind a reverse proxy (nginx, Caddy) or VPN
Use HTTPS termination at the proxy level
Restrict access by IP or network
The SSE endpoint at :8082 should be similarly protected

Backup and restore¶

The KB database is a single SQLite file containing fragments, embeddings, source metadata, the FTS index, and the query cache. Everything can be regenerated by re-ingesting your sources, but a backup avoids the time and compute cost of re-embedding.

Backup¶

Use the built-in backup command, which produces a consistent snapshot even while the server is running:

kb backup

This writes a timestamped copy to the KB data directory. Pass --out <path> to write to a specific location.

Restore¶

Restore from a backup file:

kb restore /path/to/kb-backup-20250115-030000.db

This validates that the backup is a valid SQLite database, then prompts for confirmation before overwriting:

This will replace the current database at /home/deploy/.local/share/kb/kb.db. Continue? [y/N]

Pass --force to skip the confirmation prompt (useful in scripts):

kb restore --force /path/to/backup.db

Stop the server before restoring, then restart it afterward.

Migration between machines¶

Copy the backup file to the new machine. The only requirement is that the embedding model matches — same model name and dimensions. If the models differ, re-ingest from your sources instead.

Architecture¶

                    ┌─────────────────────────────────┐
                    │         KB Server               │
                    │                                 │
                    │  kb serve                       │
                    │  ├── HTTP API    (:8080)        │
                    │  ├── MCP SSE    (:8082)         │
                    │  └── SQLite DB  (kb.db)         │
                    └──────┬──────────────┬───────────┘
                           │              │
              ┌────────────┴──┐    ┌──────┴────────────┐
              │  HTTP / CLI   │    │   MCP SSE         │
              │  --remote     │    │                   │
              ├───────────────┤    ├───────────────────┤
              │ kb query      │    │ Claude Code       │
              │ kb sources    │    │ Cursor            │
              │ kb ingest     │    │ Windsurf          │
              │ curl / scripts│    │ Any MCP client    │
              └───────────────┘    └───────────────────┘