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

Démarrage rapide (4 étapes)

Lancez un serveur d'équipe en moins de 5 minutes. Vous avez besoin de : le binaire lean-ctx (compilé avec --all-features) et un fichier de configuration JSON.

1. Créer un fichier de configuration (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. Générer un token API

# 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. Démarrer le serveur

lean-ctx team serve --config team.json

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

4. Se connecter depuis n'importe quel client

# 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"}

Référence de configuration

Le serveur d'équipe est configuré via un seul fichier JSON. Tous les paramètres peuvent être ajustés sans redémarrage - modifiez simplement le fichier et redémarrez le serveur.

Tokens et portées

Chaque membre de l'équipe reçoit un token API unique avec des portées granulaires. Les tokens sont stockés sous forme de hachages SHA-256 dans le fichier de configuration - le token en clair n'est affiché qu'une seule fois lors de la création.

Portées disponibles

# 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

Les tokens sont hachés avec SHA-256 avant le stockage. Le texte en clair est affiché une seule fois sur stdout lors de la création. Si vous perdez un token, générez-en un nouveau - il n'y a aucun moyen de récupérer l'original.

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"

Configuration multi-workspace

Servez plusieurs projets depuis une seule instance de serveur. Chaque workspace pointe vers un répertoire racine de projet différent et maintient son propre index de graphe et état de session.

{
  "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"
}

Les clients sélectionnent un workspace en ajoutant un en-tête <code>X-Workspace</code> à leurs requêtes. Si omis, la <code>defaultWorkspaceId</code> est utilisée.

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

Authentification

Chaque requête (sauf /health) nécessite un token Bearer valide dans l'en-tête Authorization. Le serveur valide le token contre les hachages SHA-256 du fichier de configuration et vérifie que les portées du token couvrent l'outil demandé.

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", ...}

Limites de débit et protection

Le serveur d'équipe inclut une limitation de débit intégrée, un contrôle de concurrence, des limites de taille de requête et des délais d'expiration. Ceux-ci protègent contre les agents incontrôlés et le déni de service accidentel.

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

Journal d'audit

Chaque appel d'outil authentifié est enregistré dans un fichier JSON Lines. Chaque entrée inclut l'horodatage, l'ID du token, le nom de l'outil, le workspace, la durée et le statut. Utilisez ceci pour le débogage, la conformité et l'attribution des coûts.

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

Synchronisation des workspaces

Maintenez les index des workspaces à jour en exécutant la commande de synchronisation. Celle-ci effectue un git fetch sur chaque workspace et reconstruit les index de graphe obsolètes. Exécutez-la via cron ou un job CI pour des workflows d'équipe entièrement automatisés.

# 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