Prerequisites

• LeanCTX installed on each developer's machine (Installation Guide)
• Docker (for containerized deployment) or a Linux/macOS server
• Network connectivity between developer machines and the server

Schnellstart (4 Schritte)

Starten Sie einen Team-Server in unter 5 Minuten. Sie benötigen: die lean-ctx-Binary (gebaut mit --all-features) und eine JSON-Konfigurationsdatei.

1. Konfigurationsdatei erstellen (team.json)

{
  "host": "0.0.0.0",
  "port": 9877,
  "defaultWorkspaceId": "main",
  "auditLogPath": "/var/log/lean-ctx/audit.log",
  "workspaces": [
    {
      "id": "main",
      "label": "Main Project",
      "root": "/home/team/project"
    }
  ],
  "tokens": []
}

2. API-Token generieren

# Generate a token with specific scopes
TOKEN="$(lean-ctx team token create \
  --config team.json \
  --id dev-alice \
  --scopes search,graph,artifacts,index,events,sessionMutations,knowledge
)"

# TOKEN is the Bearer token (printed once; config stores only sha256Hex).

3. Server starten

lean-ctx team serve --config team.json

# Team Server - 0.0.0.0:9877
# Workspaces: 1 (main)
# Tokens: 1 active
# Tools: 58 available

4. Von einem beliebigen Client verbinden

# Health check
curl http://your-server:9877/health

# List available tools (requires token)
curl -H "Authorization: Bearer $TOKEN" \
  http://your-server:9877/v1/manifest

# Call a tool (workspace defaults to defaultWorkspaceId)
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"ctx_tree","arguments":{"path":".","depth":2}}' \
  http://your-server:9877/v1/tools/call

# Call a tool in a specific workspace (header overrides default)
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "x-leanctx-workspace: main" \
  -H "Content-Type: application/json" \
  -d '{"name":"ctx_read","arguments":{"path":"README.md","mode":"signatures"}}' \
  http://your-server:9877/v1/tools/call

Docker Deployment

Run the Team Server as a Docker container for quick deployment without compiling from source.

docker run -d --name leanctx-team \
  -p 7700:7700 \
  -v leanctx-data:/data \
  ghcr.io/yvgude/lean-ctx:latest \
  serve --team --data-dir /data

Or run directly from the binary:

lean-ctx serve --team --bind 0.0.0.0:7700 --data-dir ./team-data

Verify the server is running:

curl http://your-server:7700/healthz
# {"status":"ok","version":"3.5.1","uptime":"2m"}

Konfigurationsreferenz

Der Team-Server wird über eine einzelne JSON-Datei konfiguriert. Alle Einstellungen können ohne Neustart angepasst werden - ändern Sie einfach die Datei und starten Sie den Server neu.

Tokens & Berechtigungen

Jedes Teammitglied erhält einen einzigartigen API-Token mit feingranularen Berechtigungen. Tokens werden als SHA-256-Hashes in der Konfigurationsdatei gespeichert - der Klartext-Token wird nur einmal bei der Erstellung angezeigt.

Verfügbare Berechtigungen

# Create token with all scopes
lean-ctx team token create \
  --config team.json \
  --id ci-bot \
  --scopes search,graph,artifacts,index,events,sessionMutations,knowledge,audit

# Create read-only token (search + graph only)
lean-ctx team token create \
  --config team.json \
  --id reviewer \
  --scopes search,graph

# Create agent token (read + write + events)
lean-ctx team token create \
  --config team.json \
  --id agent-alice \
  --scopes search,graph,events,sessionMutations,knowledge

Tokens werden vor der Speicherung mit SHA-256 gehasht. Der Klartext wird einmalig auf stdout bei der Erstellung ausgegeben. Bei Verlust eines Tokens generieren Sie einen neuen - es gibt keine Möglichkeit, das Original wiederherzustellen.

Connecting Agents

Each developer configures their local LeanCTX to connect to the Team Server via a config file or environment variables.

Add to .lean-ctx/config.toml:

[team]
server = "http://your-server:7700"
token = "lctx_t_alice_a3f8..."
workspace = "my-team"

Or set via environment variables:

export LEANCTX_TEAM_SERVER="http://your-server:7700"
export LEANCTX_TEAM_TOKEN="lctx_t_alice_a3f8..."
export LEANCTX_WORKSPACE="my-team"

Multi-Workspace-Einrichtung

Bedienen Sie mehrere Projekte von einer einzigen Serverinstanz. Jeder Workspace zeigt auf ein anderes Projekt-Stammverzeichnis und verwaltet seinen eigenen Graph-Index und Session-Status.

{
  "workspaces": [
    { "id": "frontend", "label": "React Frontend", "root": "/srv/frontend" },
    { "id": "backend", "label": "Rust API", "root": "/srv/backend" },
    { "id": "infra", "label": "Infrastructure", "root": "/srv/infra" }
  ],
  "defaultWorkspaceId": "frontend"
}

Clients wählen einen Workspace durch Hinzufügen eines <code>X-Workspace</code>-Headers zu ihren Anfragen. Wenn weggelassen, wird die <code>defaultWorkspaceId</code> verwendet.

Shared Sessions

Once connected, sessions are automatically shared. Agents on the same workspace and channel see each other's context in real time.

lean-ctx session list --workspace my-team

# workspace: my-team
# channel: feat/auth-refactor  rev:14  agents: cursor, claude-code
# channel: fix/api-timeout     rev:7   agents: windsurf
# channel: main                rev:42  agents: copilot, kiro

Governance & Budgets

Configure per-agent budgets, roles, and policies in your team profile to control spending and access.

[budget]
max_context_tokens = 200000
max_cost_usd = 5.0
alert_threshold = 0.8

[roles]
default = "developer"

[roles.ci]
scope = "read"
max_cost_usd = 1.0

Monitoring

The Team Server exposes Prometheus metrics and a status endpoint. Use the observatory dashboard for a visual overview.

lean-ctx observatory --open

Authentifizierung

Jede Anfrage (außer /health) erfordert einen gültigen Bearer-Token im Authorization-Header. Der Server validiert den Token gegen die SHA-256-Hashes in der Konfigurationsdatei und prüft, ob die Berechtigungen des Tokens das angeforderte Tool abdecken.

Authorization: Bearer $TOKEN

# Without token → HTTP 401 + JSON {error_code:"unauthorized", ...}
# Invalid token → HTTP 401 + JSON {error_code:"unauthorized", ...}
# Valid token, wrong scope → HTTP 403 + JSON {error_code:"scope_denied", ...}

Ratenbegrenzung & Schutz

Der Team-Server enthält integrierte Ratenbegrenzung, Parallelitätskontrolle, Anfragegrößenbeschränkungen und Timeouts. Diese schützen vor unkontrollierten Agenten und versehentlichem Denial-of-Service.

{
  "maxRps": 50,
  "rateBurst": 100,
  "maxConcurrency": 32,
  "requestTimeoutMs": 30000,
  "maxBodyBytes": 2097152
}

Audit-Log

Jeder authentifizierte Tool-Aufruf wird in einer JSON-Lines-Datei protokolliert. Jeder Eintrag enthält Zeitstempel, Token-ID, Tool-Name, Workspace, Dauer und Status. Verwenden Sie dies für Debugging, Compliance und Kostenzuordnung.

Audit log is JSONL (one JSON object per line). It never stores raw tool arguments — only argumentsMd5 of a canonicalized JSON representation.

# Inspect the latest audit entry
tail -n 1 /var/log/lean-ctx/audit.log | jq .

# Keys per entry:
# ts, tokenId, workspaceId, tool, method, allowed, deniedReason, argumentsMd5

Workspace-Synchronisation

Halten Sie Workspace-Indizes aktuell, indem Sie den Sync-Befehl ausführen. Dies führt einen git fetch auf jedem Workspace durch und baut veraltete Graph-Indizes neu auf. Führen Sie es über Cron oder einen CI-Job für vollständig automatisierte Team-Workflows aus.

# Sync all workspaces (git fetch + rebuild indexes)
lean-ctx team sync --config team.json

# Sync a specific workspace
lean-ctx team sync --config team.json --workspace backend

Next Steps

• API Reference — REST endpoints and SDK
• Profiles — Preconfigured governance presets
• Shared Sessions — Deep dive into session sharing
• Context Bus — Event-driven multi-agent coordination
• Remote Setup — Advanced remote deployment options
• Observatory — Dashboard & monitoring