From 77fc8b75c1246708cc625bf73ec886a1e1208670 Mon Sep 17 00:00:00 2001 From: Danny Avila Date: Sat, 19 Sep 2026 14:20:20 -0400 Subject: [PATCH] =?UTF-8?q?=F0=9F=A7=AD=20docs:=20Explain=20Code=20Environ?= =?UTF-8?q?ment=20Persistence?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- content/docs/features/code_interpreter.mdx | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/content/docs/features/code_interpreter.mdx b/content/docs/features/code_interpreter.mdx index 3e30c898c..db94645e3 100644 --- a/content/docs/features/code_interpreter.mdx +++ b/content/docs/features/code_interpreter.mdx @@ -80,7 +80,7 @@ With [`ordinaryToolCancellation: true`](/docs/configuration/librechat_yaml/objec ### Stateful Code Sessions -Stateful code sessions let a LibreChat Agent reuse one Code Interpreter sandbox workspace across executions. Files, installed packages, and working state usually carry over, making iterative analysis and multi-step file generation more efficient. Each agent selects one workspace scope: +Stateful code sessions let a LibreChat Agent reuse retained Code Interpreter files across executions. Each execution still starts a fresh process, and the runtime may reset. Each agent selects one workspace scope: - **User workspace (recommended):** one workspace for the signed-in user across stateful-enabled agents - **Agent + user workspace:** one workspace for each user and agent combination @@ -105,6 +105,22 @@ Stateful requests fail closed when the selected environment is missing, inaccess Stateful and stateless sessions do not share a live workspace. The stateful workspace may reset at any time, regardless of its selected scope. Save important outputs under `/mnt/data`, and do not otherwise rely on session state as durable storage. +#### What persists between executions + +Approval modes control whether an operation may run; they do not change what survives after it finishes. Managed runtimes capture retained files rather than preserving an interactive shell, while attached workers preserve files in the selected registered workspace. + +| Backend | Files available to later calls | State that is not durable | +| --- | --- | --- | +| Managed, stateless | Successful outputs retained from `/mnt/data` with supported file types | The process, shell variables, current working directory, `$HOME`, `/tmp`, environment changes, global installs, and background processes | +| Managed, stateful | Retained files under `/mnt/data`; the runtime may still reset | The process, shell variables, current working directory, `$HOME`, `/tmp`, environment changes, global installs, and background processes | +| Attached workspace | Files written inside the selected registered workspace, including dependencies installed there | The per-call process, shell variables, current working directory, `$HOME`, `/tmp` and `$TMPDIR`, environment changes, global or system installs, and background processes | + +For managed execution, write a later call's inputs under `/mnt/data` and read them back explicitly. For an attached workspace, write them under the selected project and use workspace-relative paths. Pass the working directory again when a later attached command needs a subdirectory. Keep project dependencies inside the workspace, such as a repository-local virtual environment or `node_modules`. + +Do not hand work to a later call through an exported variable, a changed shell directory, a process left running in the background, or a file in a temporary or home directory. Software installed by the machine owner can be available to attached commands, but an Agent must treat `$HOME`, global package locations, system package locations, and machine services as operator-managed rather than mutable session storage. Long-lived services should run outside an Agent command under the machine owner's service manager. + +The attached worker owns filesystem, network, and process confinement. LibreChat intersects the worker's policy with deployment, user, Agent, and conversation choices; a less restrictive approval selection cannot widen the worker's policy. Workspace persistence therefore does not imply access to the rest of the host, and a permissive worker policy does not turn call-local state into durable workspace state. + Files authored by stateful `create_file` and `edit_file` calls appear on the assistant message under an expandable **Workspace changes** row. It lists each unique changed path for that response and provides an authenticated download action. Downloads use LibreChat's persisted file flow when available and a secure Code Interpreter fallback otherwise. The row is a record of authored outputs, not a durable workspace snapshot; stateless outputs continue to appear as regular inline attachments. #### Attached environments and pairing