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

Inicio rápido (4 pasos)

Ponga en marcha un servidor de equipo en menos de 5 minutos. Necesita: el binario de lean-ctx (compilado con --all-features) y un archivo de configuración JSON.

1. Crear un archivo de configuración (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. Generar 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. Iniciar el servidor

lean-ctx team serve --config team.json

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

4. Conectar desde cualquier cliente

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

Referencia de configuración

El servidor de equipo se configura mediante un único archivo JSON. Todos los ajustes se pueden modificar sin reiniciar - simplemente modifique el archivo y reinicie el servidor.

Tokens y ámbitos

Cada miembro del equipo recibe un token API único con ámbitos detallados. Los tokens se almacenan como hashes SHA-256 en el archivo de configuración - el token en texto plano solo se muestra una vez durante la creación.

Ámbitos 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

Los tokens se hashean con SHA-256 antes del almacenamiento. El texto plano se imprime una vez en stdout durante la creación. Si pierde un token, genere uno nuevo - no hay forma de recuperar el 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"

Configuración multi-workspace

Sirva múltiples proyectos desde una única instancia de servidor. Cada workspace apunta a un directorio raíz de proyecto diferente y mantiene su propio índice de grafo y estado de sesión.

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

Los clientes seleccionan un workspace añadiendo un encabezado <code>X-Workspace</code> a sus solicitudes. Si se omite, se utiliza el <code>defaultWorkspaceId</code>.

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

Autenticación

Cada solicitud (excepto /health) requiere un token Bearer válido en el encabezado Authorization. El servidor valida el token contra los hashes SHA-256 del archivo de configuración y verifica que los ámbitos del token cubran la herramienta solicitada.

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

Límites de velocidad y protección

El servidor de equipo incluye limitación de velocidad integrada, control de concurrencia, límites de tamaño de solicitud y tiempos de espera. Estos protegen contra agentes descontrolados y denegación de servicio accidental.

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

Registro de auditoría

Cada llamada de herramienta autenticada se registra en un archivo JSON Lines. Cada entrada incluye la marca de tiempo, el ID del token, el nombre de la herramienta, el workspace, la duración y el estado. Úselo para depuración, cumplimiento y atribución de costos.

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

Sincronización de workspaces

Mantenga los índices de workspaces actualizados ejecutando el comando de sincronización. Este realiza un git fetch en cada workspace y reconstruye los índices de grafo obsoletos. Ejecútelo mediante cron o un job de CI para flujos de trabajo de equipo completamente automatizados.

# 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