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

Quick Start (4 Steps)

Get a team server running in under 5 minutes. You need: the lean-ctx binary (built with --all-features) and a JSON configuration file.

1. Create a Configuration File (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. Generate an API Token

# 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. Start the Server

lean-ctx team serve --config team.json

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

4. Connect from Any 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"}

Configuration Reference

The team server is configured via a single JSON file. All settings can be adjusted without restarting - just modify the file and restart the server.

Tokens & Scopes

Each team member gets a unique API token with fine-grained scopes. Tokens are stored as SHA-256 hashes in the config file - the plaintext token is only shown once during creation.

Available Scopes

# 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 are hashed with SHA-256 before storage. The plaintext is printed once to stdout during creation. If you lose a token, generate a new one - there is no way to recover the 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"

Multi-Workspace Setup

Serve multiple projects from a single server instance. Each workspace points to a different project root directory and maintains its own graph index and session state.

{
  "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 select a workspace by adding a <code>X-Workspace</code> header to their requests. If omitted, the <code>defaultWorkspaceId</code> is used.

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

Authentication

Every request (except /health) requires a valid Bearer token in the Authorization header. The server validates the token against the SHA-256 hashes in the config file and checks that the token's scopes cover the requested tool.

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

Rate Limits & Protection

The team server includes built-in rate limiting, concurrency control, request size limits, and timeouts. These protect against runaway agents and accidental denial-of-service.

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

Audit Log

Every authenticated tool call is logged to a JSON Lines file. Each entry includes the timestamp, token ID, tool name, workspace, duration, and status. Use this for debugging, compliance, and cost attribution.

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 Sync

Keep workspace indexes fresh by running the sync command. This performs a git fetch on each workspace and rebuilds stale graph indexes. Run it via cron or a CI job for fully automated team workflows.

# 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