Journey: Team, Cloud & Self-Hosting

One LeanCTX, one company: every developer and CI agent draws on the same compressed, governed context. This journey takes you from a single team.json to a hardened, audited service on your own infrastructure — with role-scoped tokens, account sync across your machines, headless CI and a procurement-grade ROI artifact. And one rule above all of it: local stays free.

1. Local stays free — the boundary, first

Most tools monetize by gating features. LeanCTX does the opposite: the Local-Free Invariant — enforced as a CI gate in the open repo — guarantees that no local capability is ever placed behind an account, license or plan. Billing describes plans and meters savings; it never gates:

lean-ctx billing plans               # free · team · enterprise (additive entitlements)
lean-ctx billing usage --json        # metered from the signed ledger, read-only

The open repo (Apache-2.0) carries the engine, CLI, SDKs, plugins and the self-host team server. Only a managed, multi-tenant plane — billing enforcement, SSO/SCIM — lives separately, behind the same /v1 boundary. Hosting it yourself needs none of that.

2. Team server — one shared index for many developers

lean-ctx team serve is one process that fronts many workspaces (repos) and many users. Everyone points their MCP client at its URL and queries one shared BM25 / graph / artifact index instead of each clone rebuilding its own:

lean-ctx team serve --config team.json

team.json lists the workspaces and the tokens — stored as SHA-256 hashes, never plaintext:

{
  "host": "0.0.0.0",
  "port": 8080,
  "defaultWorkspaceId": "core",
  "workspaces": [
    { "id": "core", "label": "Core API", "root": "/srv/repos/core-api" },
    { "id": "web",  "label": "Web App",  "root": "/srv/repos/web" }
  ],
  "tokens": [
    { "id": "alice",  "sha256Hex": "<sha256(token)>", "role": "member" },
    { "id": "ci-bot", "sha256Hex": "<sha256(token)>", "scopes": ["search", "graph"] }
  ],
  "auditLogPath": "/var/lib/lean-ctx/audit.jsonl"
}

Read-first by design: the team surface authorizes search, graph, knowledge, events and artifacts — but denies code-mutating/exec tools (ctx_shell, ctx_execute, ctx_edit). A shared org server hands out context, not remote shells.

Tokens, scopes and roles

Mint tokens with the CLI; the secret prints once, only its hash is stored:

lean-ctx team token create --config team.json --id alice --role member
lean-ctx team token create --config team.json --id ci-bot --scopes search,graph

Roles expand to scopes — viewer · member · admin · owner. A viewer may search but is denied mutations and audit (403 scope_denied); an admin holds the full scope set — and every decision is written to the audit log.

Scope	Grants
search	BM25 / semantic queries
graph	dependency/impact graph reads
artifacts	packed context artifacts
index	trigger/read index builds
events	event stream subscription
sessionmutations	write session state
knowledge	read/write project knowledge
audit	read the audit trail

Give a read-only CI bot search,graph; give a trusted writer knowledge too.

Keeping the shared index fresh

lean-ctx team sync --config team.json [--workspace <id>]

This git fetches the configured workspaces so the server’s index tracks the latest commits. Run it on a timer (cron, CI schedule or EventBridge) on the server host.

3. Self-host it in production

The whole runtime is one ~15 MB binary, so the container image stays tiny:

FROM debian:stable-slim
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates git curl \
 && rm -rf /var/lib/apt/lists/*
RUN curl -fsSL https://leanctx.com/install.sh | sh
ENV PATH="/root/.local/bin:${PATH}"   # adjust to your install location
COPY team.json /etc/lean-ctx/team.json
EXPOSE 8080
CMD ["lean-ctx", "team", "serve", "--config", "/etc/lean-ctx/team.json"]

Bind safety is enforced in code: the server refuses to bind a non-loopback host without a token (and the team server requires at least one). There is no accidental open endpoint.

AWS topology

A single, well-provisioned node behind a load balancer is the sweet spot:

Layer	AWS service	Why
TLS + identity	ALB (ACM cert) + authenticate-oidc	Server speaks plain HTTP — terminate TLS and add SSO at the edge
Compute	ECS Fargate task (or EC2)	One container; scale the task size, not the count
Persistent state	EFS / EBS at /srv/repos + /var/lib/lean-ctx	Indexes, caches and the audit log survive restarts
Fresh index	EventBridge schedule → team sync	git fetches each workspace so the index tracks main
Secrets	Secrets Manager / SSM for team.json	Never bake token hashes into the image

Identity & SSO

The team server authenticates bearer tokens, not users — tokens are provisioned out-of-band, least-privilege by design. For company SSO, put identity at the edge: ALB authenticate-oidc (Cognito, Okta, Entra ID) or an oauth2-proxy sidecar. Map each person and CI job to a role-scoped token; rotate by reissuing and removing the old id.

Production hardening checklist

Every item below is a real, in-code control — set it, don’t assume it:

• TLS at the ALB; the origin stays on a private subnet.
• Auth required — tokens are timing-safe compared; a non-loopback bind without a token is refused.
• Caps — maxRps, rateBurst, maxConcurrency, maxBodyBytes, requestTimeoutMs are config; tune per fleet.
• DNS-rebinding guard — allowedHosts is enforced; never set disableHostCheck in production.
• Least privilege — give CI search,graph; reserve knowledge, sessionmutations and audit for trusted roles.
• Audit — ship auditLogPath (JSONL: who · tool · workspace · allowed/denied) to CloudWatch.

Know the limits

• Single process, filesystem state. The context bus, session cache and indexes are in-process — scale vertically (bigger task + a persistent volume), not by adding nodes. There is no turnkey multi-node HA fan-out; for very large orgs, run one strong instance or shard by team.
• Repos live on the host. Workspaces point at real directories — clone them onto the volume and refresh with team sync.
• TLS is yours. The server is HTTP behind your load balancer by design.

4. Cloud account — sync your own data across machines

LeanCTX Cloud is an optional, account-based sync for a single user’s data across their own machines. It is not required for any local feature.

lean-ctx register <email>          # create an account (verification email sent)
lean-ctx login <email>             # credentials → ~/.lean-ctx/cloud/credentials.json
lean-ctx sync                      # push your local data to the cloud

sync covers: stats, command history, CEP scores, knowledge, gotchas, buddy state and feedback thresholds. Each section is skipped cleanly if there’s nothing to send (“No … to sync yet”).

Privacy: emails are masked in output; only your own account data is synced. This is distinct from contribute, which is anonymized and aggregate.

Contributing to adaptive models

lean-ctx contribute                # send anonymized compression data points
lean-ctx cloud pull-models         # pull refreshed adaptive compression models

contribute uploads anonymized compression samples that improve the shared adaptive models; cloud pull-models downloads refreshed models and prints an estimated compression improvement. Fully optional — local heuristics work without it.

5. Headless / CI usage

For pipelines you want zero prompts and deterministic exit codes.

lean-ctx bootstrap [--json]        # = setup --non-interactive --yes --fix
lean-ctx serve                     # MCP server (stdio) — for agent runners
lean-ctx daemon                    # background daemon (index/event services)

Both setup paths exit non-zero on failure, so a CI step fails loudly; --json emits a machine-readable report. Provider integrations (GitHub/GitLab/Jira/Postgres) read credentials from environment variables, never from prompts — store them as CI secrets and they run headless.

For verifiable context in CI gates, pair with ctx_proof (cryptographic proof a context was produced as claimed) and ctx_verify (validate an artifact/ledger) — see the Prove It journey.

6. Prove the value — a signed ROI artifact

lean-ctx savings roi               # net tokens, USD, top tools — SHA-256 chain + Ed25519 signature

One command turns the metered ledger into a reproducible, signed ROI number you can hand to procurement or finance.

7. Choosing the right sharing model

You want…	Use
Many devs sharing one index	team serve + scoped tokens (§2)
The server on your own infra	Docker / AWS topology (§3)
Your data on your machines	login + sync (§4)
Help improve compression for everyone	contribute (§4)
Headless install/verify in pipelines	bootstrap, serve, ctx_proof (§5)
A signed ROI number for procurement	savings roi (§6)
Agents coordinating on one repo	Multi-Agent journey

Storage & config (team/cloud)

Path	Contents
team.json (your path)	team server config + token hashes
~/.lean-ctx/cloud/credentials.json	cloud login credentials
~/.lean-ctx/cloud/	synced-data staging
/var/lib/lean-ctx/audit.jsonl	team server audit trail (self-host)