♨️ feat: Prewarm Stateful Code Sandboxes with Cold-Boot UX Feedback

api/server/controllers/agents/callbacks.js

@@ -3,6 +3,7 @@ const { logger } = require('@librechat/data-schemas');
 const {
   Tools,
   StepTypes,
+  StepEvents,
   FileContext,
   ErrorTypes,
   UsageEvents,
@@ -21,6 +22,7 @@ const {
   createToolExecuteHandler,
   HOST_FILE_AUTHORING_ARTIFACT_KEY,
   isCodeSessionToolName,
+  shouldSignalSandboxStart,
 } = require('@librechat/api');
 const { processFileCitations } = require('~/server/services/Files/Citations');
 const { processCodeOutput, runPreviewFinalize } = require('~/server/services/Files/Code/process');
@@ -228,6 +230,37 @@ async function emitEvent(res, streamId, eventData) {
   }
 }
 
+/**
+ * Emits `on_sandbox_starting` for each code-execution tool call in the run
+ * step when the conversation's stateful sandbox is still cold-booting, so the
+ * UI can explain the first call's boot latency instead of showing a generic
+ * running state. Only signals while a fired prewarm remains unresolved
+ * ({@link shouldSignalSandboxStart}); stateless deployments never fire one
+ * and completed boots clear the marker, so both stay on the generic label.
+ * @param {ServerResponse} res - The server response object
+ * @param {string | null} streamId - The stream ID for resumable mode, or null for standard mode
+ * @param {StreamEventData} data - The `on_run_step` event data
+ * @param {GraphRunnableConfig['configurable']} [metadata] The runnable metadata
+ * @returns {Promise<void>}
+ */
+async function maybeEmitSandboxStarting(res, streamId, data, metadata) {
+  const conversationId = metadata?.thread_id;
+  if (!conversationId || !(await shouldSignalSandboxStart(conversationId))) {
+    return;
+  }
+  const toolCalls = data?.stepDetails?.tool_calls ?? [];
+  for (const toolCall of toolCalls) {
+    const name = toolCall?.name ?? toolCall?.function?.name;
+    if (!toolCall?.id || name == null || !isCodeSessionToolName(name)) {
+      continue;
+    }
+    await emitEvent(res, streamId, {
+      event: StepEvents.ON_SANDBOX_STARTING,
+      data: { tool_call_id: toolCall.id, runId: metadata?.run_id },
+    });
+  }
+}
+
 /**
  * Maps a {@link SubagentUpdateEvent} phase to the corresponding
  * {@link GraphEvents} name that the SDK's `createContentAggregator`
@@ -363,6 +396,7 @@ function getDefaultHandlers({
         aggregateContent({ event, data });
         if (data?.stepDetails.type === StepTypes.TOOL_CALLS) {
           await emitEvent(res, streamId, { event, data });
+          await maybeEmitSandboxStarting(res, streamId, data, metadata);
         } else if (checkIfLastAgent(metadata?.last_agent_id, metadata?.langgraph_node)) {
           await emitEvent(res, streamId, { event, data });
         } else if (!metadata?.hide_sequential_outputs) {

api/server/controllers/agents/client.js

@@ -68,6 +68,7 @@ const {
   appendYouTubeVideoParts,
   resolveYouTubeInjectionConfig,
   decrementPendingRequest,
+  maybePrewarmCodeSandbox,
 } = require('@librechat/api');
 const {
   Callback,
@@ -1386,6 +1387,16 @@ class AgentClient extends BaseClient {
         abortController = new AbortController();
       }
 
+      /** Fire-and-forget: boot the per-conversation stateful sandbox in
+       *  parallel with generation so the first execute_code/bash call lands
+       *  on a warm VM. No-op unless a reachable agent resolved
+       *  `statefulCodeSessions`. */
+      maybePrewarmCodeSandbox({
+        req: this.options.req,
+        conversationId: this.conversationId,
+        agents: [this.options.agent, ...(this.agentConfigs?.values() ?? [])],
+      });
+
       /** @type {AppConfig['endpoints']['agents']} */
       const agentsEConfig = appConfig.endpoints?.[EModelEndpoint.agents];
 

client/src/components/Chat/Messages/Content/Part.tsx

@@ -151,6 +151,8 @@ const Part = memo(function Part({
     const isToolCall =
       'args' in toolCall && (!toolCall.type || toolCall.type === ToolCallTypes.TOOL_CALL);
     if (isToolCall) {
+      const toolCallId =
+        'id' in toolCall && typeof toolCall.id === 'string' ? toolCall.id : undefined;
       const card = (() => {
         if (isBashProgrammaticToolCall(toolCall.name, toolCall.args)) {
           return (
@@ -163,6 +165,7 @@ const Part = memo(function Part({
               commandField="code"
               hideAttachments={hideAttachments}
               onExpand={onToolExpand}
+              toolCallId={toolCallId}
             />
           );
         } else if (
@@ -179,6 +182,7 @@ const Part = memo(function Part({
               args={toolCall.args}
               hideAttachments={hideAttachments}
               onExpand={onToolExpand}
+              toolCallId={toolCallId}
             />
           );
         } else if (
@@ -279,6 +283,7 @@ const Part = memo(function Part({
               attachments={attachments}
               hideAttachments={hideAttachments}
               onExpand={onToolExpand}
+              toolCallId={toolCallId}
             />
           );
         } else if (toolCall.name === Tools.web_search) {

client/src/components/Chat/Messages/Content/Parts/BashCall.tsx

@@ -1,14 +1,16 @@
 import { useMemo, useRef, useState, useCallback, useEffect } from 'react';
 import copy from 'copy-to-clipboard';
+import { useRecoilValue } from 'recoil';
 import type { TAttachment } from 'librechat-data-provider';
 import ProgressText from '~/components/Chat/Messages/Content/ProgressText';
+import parseJsonField, { areToolCallArgsComplete } from './parseJsonField';
 import CopyButton from '~/components/Messages/Content/CopyButton';
 import LangIcon from '~/components/Messages/Content/LangIcon';
+import { sandboxStartingByToolCallId } from '~/store';
 import useToolCallState from './useToolCallState';
 import useLazyHighlight from './useLazyHighlight';
 import { ERROR_PATTERNS } from './ExecuteCode';
 import { AttachmentGroup } from './Attachment';
-import parseJsonField, { areToolCallArgsComplete } from './parseJsonField';
 import { useLocalize } from '~/hooks';
 import { cn } from '~/utils';
 
@@ -21,6 +23,7 @@ export default function BashCall({
   commandField = 'command',
   hideAttachments = false,
   onExpand,
+  toolCallId,
 }: {
   initialProgress: number;
   isSubmitting: boolean;
@@ -30,10 +33,12 @@ export default function BashCall({
   commandField?: string;
   hideAttachments?: boolean;
   onExpand?: () => void;
+  toolCallId?: string;
 }) {
   const localize = useLocalize();
   const command = useMemo(() => parseJsonField(args, commandField), [args, commandField]);
   const isWritingCommand = !command || !areToolCallArgsComplete(args);
+  const sandboxStarting = useRecoilValue(sandboxStartingByToolCallId(toolCallId ?? ''));
 
   const { showCode, toggleCode, expandStyle, expandRef, progress, cancelled, hasError, hasOutput } =
     useToolCallState(initialProgress, isSubmitting, output, !!command, onExpand);
@@ -52,17 +57,23 @@ export default function BashCall({
     timerRef.current = setTimeout(() => setIsCopied(false), 3000);
   }, [command]);
 
+  const inProgressText = (() => {
+    if (isWritingCommand) {
+      return localize('com_ui_writing_command');
+    }
+    if (sandboxStarting) {
+      return localize('com_ui_sandbox_starting');
+    }
+    return localize('com_ui_running_command');
+  })();
+
   return (
     <>
       <div className="relative my-1.5 flex size-5 shrink-0 items-center gap-2.5">
         <ProgressText
           progress={progress}
           onClick={toggleCode}
-          inProgressText={
-            isWritingCommand
-              ? localize('com_ui_writing_command')
-              : localize('com_ui_running_command')
-          }
+          inProgressText={inProgressText}
           finishedText={
             cancelled ? localize('com_ui_cancelled') : localize('com_ui_command_finished')
           }

client/src/components/Chat/Messages/Content/Parts/ExecuteCode.tsx

@@ -1,7 +1,9 @@
 import { useMemo } from 'react';
+import { useRecoilValue } from 'recoil';
 import { SquareTerminal } from 'lucide-react';
 import type { TAttachment } from 'librechat-data-provider';
 import ProgressText from '~/components/Chat/Messages/Content/ProgressText';
+import { sandboxStartingByToolCallId } from '~/store';
 import useLazyHighlight from './useLazyHighlight';
 import useToolCallState from './useToolCallState';
 import CodeWindowHeader from './CodeWindowHeader';
@@ -58,6 +60,7 @@ export default function ExecuteCode({
   attachments,
   hideAttachments = false,
   onExpand,
+  toolCallId,
 }: {
   initialProgress: number;
   isSubmitting: boolean;
@@ -66,9 +69,11 @@ export default function ExecuteCode({
   attachments?: TAttachment[];
   hideAttachments?: boolean;
   onExpand?: () => void;
+  toolCallId?: string;
 }) {
   const localize = useLocalize();
   const { lang = 'py', code } = useParseArgs(args) ?? ({} as ParsedArgs);
+  const sandboxStarting = useRecoilValue(sandboxStartingByToolCallId(toolCallId ?? ''));
 
   const { showCode, toggleCode, expandStyle, expandRef, progress, cancelled, hasError, hasOutput } =
     useToolCallState(initialProgress, isSubmitting, output, !!code, onExpand);
@@ -82,7 +87,9 @@ export default function ExecuteCode({
         <ProgressText
           progress={progress}
           onClick={toggleCode}
-          inProgressText={localize('com_ui_analyzing')}
+          inProgressText={
+            sandboxStarting ? localize('com_ui_sandbox_starting') : localize('com_ui_analyzing')
+          }
           finishedText={
             cancelled ? localize('com_ui_cancelled') : localize('com_ui_analyzing_finished')
           }

client/src/hooks/SSE/useStepHandler.ts

@@ -17,6 +17,7 @@ import type {
   SummaryContentPart,
   TMessageContentParts,
   SubagentUpdateEvent,
+  SandboxStartingEvent,
 } from 'librechat-data-provider';
 import type { SetterOrUpdater } from 'recoil';
 import type { AnnounceOptions } from '~/common';
@@ -26,8 +27,8 @@ import {
   initSubagentAggregatorState,
   initSubagentTickerState,
 } from '~/utils/subagentContent';
+import { subagentProgressByToolCallId, sandboxStartingByToolCallId } from '~/store';
 import { isAskUserQuestionPart } from '~/utils/approval';
-import { subagentProgressByToolCallId } from '~/store';
 import { MESSAGE_UPDATE_INTERVAL } from '~/common';
 
 type TUseStepHandler = {
@@ -55,7 +56,8 @@ type TStepEvent =
   | { event: StepEvents.ON_SUMMARIZE_START; data: Agents.SummarizeStartEvent }
   | { event: StepEvents.ON_SUMMARIZE_DELTA; data: Agents.SummarizeDeltaEvent }
   | { event: StepEvents.ON_SUMMARIZE_COMPLETE; data: Agents.SummarizeCompleteEvent }
-  | { event: StepEvents.ON_SUBAGENT_UPDATE; data: SubagentUpdateEvent };
+  | { event: StepEvents.ON_SUBAGENT_UPDATE; data: SubagentUpdateEvent }
+  | { event: StepEvents.ON_SANDBOX_STARTING; data: SandboxStartingEvent };
 
 type MessageDeltaUpdate = { type: ContentTypes.TEXT; text: string; tool_call_ids?: string[] };
 
@@ -284,6 +286,41 @@ export default function useStepHandler({
     [],
   );
 
+  /** Tool-call ids whose sandbox-starting atom is set, so completion can clear them. */
+  const knownSandboxAtomKeys = useRef(new Set<string>());
+
+  const setSandboxStarting = useRecoilCallback(
+    ({ set }) =>
+      (toolCallId: string): void => {
+        knownSandboxAtomKeys.current.add(toolCallId);
+        set(sandboxStartingByToolCallId(toolCallId), true);
+      },
+    [],
+  );
+
+  const clearSandboxStarting = useRecoilCallback(
+    ({ reset }) =>
+      (toolCallId?: string | null): void => {
+        if (!toolCallId || !knownSandboxAtomKeys.current.has(toolCallId)) {
+          return;
+        }
+        knownSandboxAtomKeys.current.delete(toolCallId);
+        reset(sandboxStartingByToolCallId(toolCallId));
+      },
+    [],
+  );
+
+  const resetSandboxAtoms = useRecoilCallback(
+    ({ reset }) =>
+      (): void => {
+        for (const toolCallId of knownSandboxAtomKeys.current) {
+          reset(sandboxStartingByToolCallId(toolCallId));
+        }
+        knownSandboxAtomKeys.current.clear();
+      },
+    [],
+  );
+
   /**
    * Calculate content index for a run step.
    * For edited content scenarios, offset by initialContent length.
@@ -934,6 +971,7 @@ export default function useStepHandler({
         const { result } = stepEvent.data;
 
         const { id: stepId } = result;
+        clearSandboxStarting(result.tool_call?.id);
 
         const runStep = stepMap.current.get(stepId);
         let responseMessageId = runStep?.runId ?? '';
@@ -977,6 +1015,8 @@ export default function useStepHandler({
             }),
           );
         }
+      } else if (stepEvent.event === StepEvents.ON_SANDBOX_STARTING) {
+        setSandboxStarting(stepEvent.data.tool_call_id);
       } else if (stepEvent.event === StepEvents.ON_SUBAGENT_UPDATE) {
         applySubagentUpdate(stepEvent.data);
       } else if (stepEvent.event === StepEvents.ON_SUMMARIZE_START) {
@@ -1082,6 +1122,8 @@ export default function useStepHandler({
       calculateContentIndex,
       getCurrentMessages,
       applySubagentUpdate,
+      setSandboxStarting,
+      clearSandboxStarting,
       onSkillAuthoringComplete,
     ],
   );
@@ -1098,6 +1140,11 @@ export default function useStepHandler({
     subagentRunToToolCallId.current.clear();
     claimedSubagentToolCallIds.current.clear();
     pendingSubagentBuffer.current.clear();
+    /** Unlike subagent atoms below, sandbox-starting flags are transient
+     *  status with no audit value — reset them at this boundary so an
+     *  interrupted cold boot can't leak a stale "starting" label onto a
+     *  later tool call that reuses the same id (e.g. `call_0`). */
+    resetSandboxAtoms();
     /** Intentionally NOT calling `resetSubagentAtoms()` here — users need
      *  to be able to reopen the SubagentCall dialog after completion to
      *  audit what the child did. `resetSubagentAtoms` is returned below
@@ -1106,7 +1153,7 @@ export default function useStepHandler({
      *  persisted `subagent_content` takes over for historical messages
      *  once the conversation is saved, and we prevent unbounded
      *  atomFamily growth across multi-conversation sessions. */
-  }, []);
+  }, [resetSandboxAtoms]);
 
   /**
    * Sync a message into the step handler's messageMap.

client/src/locales/en/translation.json

@@ -1639,6 +1639,7 @@
   "com_ui_running": "Running...",
   "com_ui_running_command": "Running command",
   "com_ui_running_n_agents": "Running {{0}} agents",
+  "com_ui_sandbox_starting": "Starting sandbox environment",
   "com_ui_save": "Save",
   "com_ui_save_badge_changes": "Save badge changes?",
   "com_ui_save_changes": "Save Changes",

client/src/store/index.ts

@@ -16,6 +16,7 @@ export * from './agents';
 export * from './mcp';
 export * from './favorites';
 export * from './subagents';
+export * from './sandbox';
 export * from './usage';
 
 export default {

client/src/store/sandbox.ts

@@ -0,0 +1,13 @@
+import { atomFamily } from 'recoil';
+
+/**
+ * True while the backend reported the stateful code sandbox is cold-booting
+ * for this tool call (`on_sandbox_starting` SSE event). Keyed by
+ * `tool_call_id`; `ExecuteCode`/`BashCall` swap their in-progress label to a
+ * "starting sandbox" message while set. Cleared when the tool call's run
+ * step completes.
+ */
+export const sandboxStartingByToolCallId = atomFamily<boolean, string>({
+  key: 'sandboxStartingByToolCallId',
+  default: false,
+});