LibreChat/docs/workspace-checkouts.md
Danny Avila 35a2bee409
Some checks are pending
Backend Unit Tests / Build packages (push) Waiting to run
Backend Unit Tests / Codegraph select (push) Waiting to run
Backend Unit Tests / TypeScript type checks (push) Blocked by required conditions
Backend Unit Tests / Circular dependency checks (push) Waiting to run
Backend Unit Tests / Tests: api (shard 1/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: api (shard 2/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: api (shard 3/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: data-provider (push) Blocked by required conditions
Backend Unit Tests / Tests: data-schemas (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 1/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 2/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 3/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 4/4) (push) Blocked by required conditions
Codegraph E2E Votes / vote (full suite) (push) Waiting to run
Docker Dev Branch Images Build / publish (push) Waiting to run
Frontend Unit Tests / Client build recovery regression (push) Waiting to run
Frontend Unit Tests / Codegraph select (push) Waiting to run
Frontend Unit Tests / Build packages (push) Waiting to run
Frontend Unit Tests / TypeScript type checks (client) (push) Blocked by required conditions
Frontend Unit Tests / Tests: @librechat/client (push) Blocked by required conditions
Frontend Unit Tests / Tests: Ubuntu (shard 1/2) (push) Blocked by required conditions
Frontend Unit Tests / Tests: Ubuntu (shard 2/2) (push) Blocked by required conditions
Frontend Unit Tests / Vite build verification (push) Blocked by required conditions
Sync Locize Translations & Create Translation PR / Sync Translation Keys with Locize (push) Waiting to run
Sync Locize Translations & Create Translation PR / Create Translation PR on Version Published (push) Blocked by required conditions
🗂️ feat: Choose Conversation Checkout Mode (#16679)
* feat: Choose the conversation checkout mode

* fix: Preserve checkout choices across submission and recovery

* test: Match checkout policy defaults and share mode enum

* fix: Offer shared checkout and require deliberate transition modes

* fix: Retain explicit mode when changing repository selection

* test: Match repository menu accessible labels
2026-10-02 14:41:35 -04:00

2.8 KiB

Conversation checkout choices

A new coding chat can use the registered checkout directly or request its own isolated worktree. The choice is part of the conversation's existing machine and workspace decision, not a separate browser preference. Opening the picker does not create a checkout; the worker provisions isolation on the first workspace operation.

Enable

First update every LibreChat API replica and client. Then opt in on the attached environment (or the control plane whose schema personal environments inherit):

configSchema:
  workspaces:
    allowCheckoutSelection: true

The isolated choice requires the selected worker workspace to advertise workspaceInstances: [git_worktree]. A worker configured with --conversation-worktree-root can advertise this capability; use a private storage directory outside its registered roots. Follow the worker's admission, capacity and setup runbook. Do not restart workers with active assignments. Conversation-worktree provisioning and linked-worktree lanes are different worker configurations and cannot be enabled together on the same worker.

In the composer workspace menu, select a repository, reopen the menu and choose Isolated worktree or Registered checkout. The recorded mode stays visible after reload. Once the chat's decision is sealed, the picker does not implicitly change that execution target. Continue without a workspace or explicitly attach again through the deployment's supported decision transitions. Those transitions offer the same checkout choices. A registered checkout is available even on a worker without isolation support. Mixed predecessor modes require an explicit choice before confirmation; they never become automatic shared-root execution silently.

  • Isolated worktree uses the worker's admitted Git snapshot. It does not copy uncommitted source changes. An unavailable isolation capability fails closed; the next command never falls back to shared source files.
  • Registered checkout uses the existing registered root. Other chats may share those files. Normal workspace authorization, approvals, sandboxing and scheduling still apply.

No flag and no recorded checkout mode preserves the existing behavior: workers advertising conversation worktrees use them automatically, and other workers operate in the registered root. No migration is needed for old chats. Stored explicit modes require compatible readers; do not enable the flag during a rolling upgrade or roll back to an older reader while such chats are active.

This control does not select a Git base ref, create a named linked-worktree lane, archive source, or remove dependencies. The descriptor's environment.ref is operator metadata, not proof of the source's current HEAD. Arbitrary base-ref selection and archive/restore need additional worker-owned protocol operations.