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 في ملف الإعدادات - يُعرض الرمز النصي مرة واحدة فقط عند الإنشاء.

النطاقات المتاحة

# 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 عند الإنشاء. إذا فقدت رمزاً، أنشئ واحداً جديداً - لا توجد طريقة لاستعادة الرمز الأصلي.

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) يتطلب رمز Bearer صالحاً في رأس Authorization. يتحقق الخادم من الرمز مقابل تجزئات 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", ...}

حدود المعدل والحماية

يتضمن خادم الفريق تحديد معدل مدمج، والتحكم في التزامن، وحدود حجم الطلب، والمهل الزمنية. هذه تحمي من العملاء الخارجين عن السيطرة ورفض الخدمة العرضي.

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

سجل التدقيق

يتم تسجيل كل استدعاء أداة مصادق عليه في ملف JSON Lines. يتضمن كل سجل الطابع الزمني ومعرف الرمز واسم الأداة ومساحة العمل والمدة والحالة. يُستخدم للتصحيح والامتثال وإسناد التكلفة.

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