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

クイックスタート（4ステップ）

5分以内にチームサーバーを起動します。必要なもの：lean-ctx バイナリ（--all-features でビルド）と JSON 設定ファイル。

1. 設定ファイルの作成（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 トークンの生成

# 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. サーバーの起動

lean-ctx team serve --config team.json

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

4. 任意のクライアントから接続

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

設定リファレンス

チームサーバーは単一の JSON ファイルで設定されます。すべての設定は再起動なしで調整可能です--ファイルを変更してサーバーを再起動するだけです。

トークンとスコープ

各チームメンバーは、きめ細かいスコープを持つ固有の API トークンを取得します。トークンは SHA-256 ハッシュとして設定ファイルに保存されます--プレーンテキストトークンは作成時に1度だけ表示されます。

利用可能なスコープ

# 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

トークンは保存前に SHA-256 でハッシュ化されます。プレーンテキストは作成時に stdout に1度だけ出力されます。トークンを紛失した場合は新しいトークンを生成してください--元のトークンを復元する方法はありません。

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"

マルチワークスペース設定

単一のサーバーインスタンスから複数のプロジェクトを提供します。各ワークスペースは異なるプロジェクトルートディレクトリを指し、独自のグラフインデックスとセッション状態を維持します。

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

クライアントはリクエストに <code>X-Workspace</code> ヘッダーを追加してワークスペースを選択します。省略した場合、<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

認証

すべてのリクエスト（/health を除く）は、Authorization ヘッダーに有効な Bearer トークンが必要です。サーバーは設定ファイルの SHA-256 ハッシュに対してトークンを検証し、トークンのスコープがリクエストされたツールをカバーしているかを確認します。

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

レート制限と保護

チームサーバーにはレート制限、同時実行制御、リクエストサイズ制限、タイムアウトが組み込まれています。これらは暴走する Agent や偶発的なサービス拒否を防ぎます。

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

監査ログ

認証されたすべてのツール呼び出しが JSON Lines ファイルに記録されます。各エントリにはタイムスタンプ、トークン ID、ツール名、ワークスペース、所要時間、ステータスが含まれます。デバッグ、コンプライアンス、コスト帰属に使用します。

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

ワークスペース同期

同期コマンドを実行してワークスペースインデックスを最新に保ちます。各ワークスペースで git fetch を実行し、古くなったグラフインデックスを再構築します。cron または CI ジョブで実行すれば、完全に自動化されたチームワークフローを実現できます。

# 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