BYOK & enterprise deployment

What it does. Master opt-in for cloud LLM routing from the extension. When true, the extension may set prefer_cloud on chat requests if a provider key exists and the model picker allows cloud. When false, all generation stays on local Ollama regardless of keys.

When to enable. Your security team has approved external inference for chat generation and you have a provider API key.

When to disable. Sovereign / air-gapped workflows, trial installs, or any environment where source-derived context must not leave your network.

How to change.

1. Open VS Code → Settings → search cloud enabled.
2. Check ContextMint: Enable Cloud LLM Provider Routing, or add to settings.json:

   "contextmint.cloudEnabled": true

3. Send a new chat message — no server restart required.

What it does. Stores provider API keys in VS Code SecretStorage (encrypted OS keychain). Supported providers: OpenAI, Anthropic, Groq. Keys are read by the extension at send time — they are never written to Engine config, server YAML, or server logs.

When to run. After enabling contextmint.cloudEnabled and before selecting Cloud / Auto in the model picker.

How to change.

1. Ctrl+Shift+P → ContextMint: Configure Cloud API Key (Preview).
2. Choose provider → paste key → confirm.
3. To rotate or remove a key, run the command again and overwrite or clear the prompt.

Verify: Compose model picker shows Cloud tier options; a test send with Cloud selected should not prompt for a missing key.

What it does. Controls routing for this send only (choice is remembered in the workspace until you change it). BYOK must already be on (contextmint.cloudEnabled + at least one stored key + server allow_cloud_dispatch) before cloud handoff can occur.

How to change. Chat compose bar → model dropdown → pick Local, Auto, or Cloud → send. Routing badge on the answer shows local or cloud tier used.

If cloud fails (rate limit, outage, missing key), the extension can fall back to local Ollama for that message. See Troubleshooting → Cloud.

What it does. You can store up to three keys — one each for openai, anthropic, and groq. They live in separate SecretStorage slots (contextmint.apiKey.openai, etc.). Keys are never merged or sent to the Python server.

Which key is used. You do not pick the provider per message in Settings. The server routing decision names a model (e.g. claude-3-5-sonnet → Anthropic, groq/llama3-70b → Groq, gpt-4o → OpenAI); the extension maps that model to the matching stored key at cloud_dispatch time. If the routed provider has no key, VS Code prompts once via Configure Cloud API Key flow.

How to add or rotate keys.

1. Ctrl+Shift+P → ContextMint: Configure Cloud API Key (Preview).
2. Quick-pick openai, anthropic, or groq.
3. Paste the key → repeat for each provider you need.
4. Run again with a new value to rotate; clearing is done through the same prompt (cancel = no change).

Tip: Store only providers your org approves. With Auto picker, a “explain this architecture” question may route to Anthropic (mid tier) while a codegen task may route to premium tier — each uses its own key if configured.

What it does. When using your own Anthropic or OpenAI reasoning models, requests and streams model-level “thinking” / extended reasoning from the provider.

When to disable. Latency-sensitive workflows or providers that do not support thinking streams.

How to change. Settings → search cloud thinking, or:

"contextmint.chat.cloudThinkingEnabled": false

Related budgets: contextmint.chat.cloudThinkingBudgetTokens (default 10000) and contextmint.chat.cloudThinkingBudgetMinTokens (default 1024) — adjust in Settings if Claude extended thinking is clipped.

What it does. Server-side gate for cloud_dispatch SSE events. When false, the API ignores prefer_cloud from the extension and always runs local Ollama — even if the developer enabled cloudEnabled and configured keys.

When to enable. Platform policy allows cloud handoff and you operate a paid or approved install (not trial / sovereign default).

How to change.

1. Option A — overlay YAML — add to ~/.contextmint/server.defaults.yaml on the API host:

   allow_cloud_dispatch: true

2. Option B — environment — in the server .env or container spec:

   ALLOW_CLOUD_DISPATCH=true

3. Restart the API (Engine → Server → restart, or redeploy container).
4. Re-test: extension with cloudEnabled + key → Cloud model → badge should show cloud tier.

What it does. When true, image attachments are not silently sent to cloud vision — the user must explicitly select a cloud vision model in compose. Preserves sovereign default for screenshots and UI captures.

How to change. In server overlay under the chat: section:

chat:
  image_cloud_opt_in_only: true

What it does. When both local and cloud vision are available and the user opted into cloud, controls whether cloud is preferred over local Ollama vision. Default false keeps local vision primary.

When to enable. Org standard is cloud-only vision and local Ollama vision is a fallback only.

How to change. Server overlay:

chat:
  image_prefer_cloud_when_both: false

What it does. Requires a valid Bearer JWT on protected /api/v1/* routes. Off for local-first single-user installs; on for shared team servers.

How to change.

1. Server overlay:

   auth:
     enabled: true

2. Or env: AUTH__ENABLED=true
3. Set JWT secret (below) before enabling in production.
4. Restart API.

What it does. local = no auth validation. oidc = validate JWT issuer, audience, and signature on incoming requests from the extension.

How to change. Server overlay:

auth:
  mode: oidc

What they do. When set, the API rejects tokens whose iss or aud claims do not match — tying extension Bearer tokens to your IdP (Microsoft Entra ID, Okta, Keycloak, etc.).

How to change. Server overlay (example for Entra ID):

auth:
  oidc_issuer: "https://login.microsoftonline.com/{tenant-id}/v2.0"
  oidc_audience: "{application-client-id}"

Obtain issuer and audience from your IdP app registration. Must match tokens VS Code forwards when enterpriseMode is enabled.

What it does. HMAC secret for HS256 JWT validation (auth.jwt_algorithm). Required when auth.enabled is true. Maps to auth.jwt_secret in server config.

How to change.

1. Generate a strong random string (32+ bytes).
2. Add to API host .env (or container secret store):

   AUTH__JWT_SECRET=your-long-random-secret-here

3. Never commit to git or paste into server.defaults.yaml.
4. Restart API after rotation; developers re-authenticate in VS Code.

What they do. require_workspace_acl enforces per-workspace roles (viewer, dev, admin) on query routes. sso_default_role (default viewer) is granted on first SSO login when no explicit role exists.

How to change. Server overlay:

auth:
  require_workspace_acl: true
  sso_default_role: viewer

What it does. When non-empty, rejects workspace registration for paths outside listed directories — useful to sandbox indexing to approved mount points.

How to change. Server overlay:

allowed_workspace_roots:
  - /data/repos
  - /mnt/shared-engineering

What it does. Base URL for all ContextMint API calls (health, indexing, chat). Local-first default is loopback; enterprise mode points at your team host.

How to change.

1. Settings → search server url, or:

   "contextmint.serverUrl": "https://contextmint.corp.example"

2. Use HTTPS internal hostname; include port only if not 443.
3. Reload window or wait for next health poll — status bar should show team server connected.

Local-first: leave default http://127.0.0.1:8000 when using Engine on the same machine.

What it does. Switches the extension to enterprise connectivity: VS Code OIDC sign-in forwards a Bearer token on every API request. If the team server is unreachable, falls back to contextmint.localFallbackUrl (if configured).

When to enable. contextmint.serverUrl points at a shared server with auth.enabled: true.

When to disable. Local-first Engine on loopback, lab VLAN without SSO, or Hub71-style “extension-only” laptops hitting a team GPU host without JWT.

How to change.

"contextmint.enterpriseMode": true

What it does. Tells VS Code which built-in authentication provider to use for SSO when enterpriseMode is on — e.g. microsoft, github, or a custom provider ID from your VS Code auth extension.

How to change.

"contextmint.oidcProviderId": "microsoft"

What it does. When enterpriseMode is enabled and the team serverUrl is down, the extension retries against this loopback Engine URL so developers can keep working offline.

When to set. Developers also run local Engine as a break-glass fallback.

How to change.

"contextmint.localFallbackUrl": "http://127.0.0.1:8000"

What it does. Optional HS256 secret for auto-signed localhost JWTs when testing auth against a local Engine. When empty, the extension reads AUTH__JWT_SECRET from the workspace .env file.

When to use. Local dev only — matching a local API with auth.enabled without full OIDC. Prefer OIDC + enterpriseMode for real team servers.

How to change. Settings → search local jwt, or set in settings.json. Do not commit secrets to workspace git.