Sandbox - Docs by LangChain

Coding agents need more than a chat window. They need a file browser, a code viewer, and a diff panel, an IDE experience. This pattern connects a deep agent to a sandbox so it can read, write, and execute code in an isolated environment, then exposes the sandbox filesystem through a custom API server so the frontend can display files in real time as the agent works. This page covers the three-panel UI (file tree, code viewer, and chat) and the custom API routes that expose the sandbox filesystem to it. For sandbox providers, lifecycle scoping, seeding files, secrets, deployment, and production useStream configuration, see Going to production.

Architecture

This setup has three parts:

Deep agent with a sandbox backend: The agent gets filesystem tools (read_file, write_file, edit_file, execute) automatically from the sandbox
Custom API server — A FastAPI app exposed via langgraph.json’s http.app field, providing file browsing endpoints the frontend can call
Three-panel frontend: A file tree, code/diff viewer, and chat panel that syncs files in real time as the agent makes changes

Sandbox lifecycle

Choose how long a sandbox lives and who shares it before wiring the frontend. See Sandbox lifecycle for thread-scoped vs assistant-scoped sandboxes, async graph factory setup, TTL behavior, and SDK invocation examples. This guide uses thread-scoped sandboxes by default. The frontend and custom API server both resolve the sandbox from the LangGraph thread ID. That keeps conversations isolated and lets page reloads reconnect to the same environment when you persist the thread ID. For multi-tenant apps, scope sandboxes by user or assistant in your backend factory instead. For demos without LangGraph threads, pass a client-generated session ID in the API URL. The session ID does not persist across browser sessions.

Connect the agent and API server

Configure the deep agent with a sandbox backend as described in Execution environment. The agent gets filesystem tools and an execute tool automatically; no extra tool configuration is needed. Building this UI adds one requirement on top of the production setup: a custom API server which runs outside the agent graph, so both the agent backend and your file-browsing routes must resolve the same sandbox for each thread. Store the sandbox ID on thread metadata and share a single lookup function between them.

Resolve the sandbox from thread metadata

from deepagents import create_deep_agent
from deepagents.backends.langsmith import LangSmithSandbox
from langgraph.config import get_config


def get_or_create_sandbox_for_thread(thread_id: str) -> LangSmithSandbox:
    if not thread_id:
        raise ValueError("thread_id is required")
    # Look up sandbox_id from thread metadata, create if missing, and seed files.
    raise NotImplementedError(
        "Implement sandbox lookup and creation for your deployment environment."
    )


def get_thread_id_from_config() -> str:
    configurable = get_config().get("configurable", {})
    thread_id = configurable.get("thread_id")
    if not thread_id:
        raise ValueError("No thread_id, agent must run on a thread")
    return thread_id


def agent():
    return create_deep_agent(
        model="google_genai:gemini-3.5-flash",
        backend=lambda _runtime: get_or_create_sandbox_for_thread(
            get_thread_id_from_config()
        ),
    )

from deepagents import create_deep_agent
from deepagents.backends.langsmith import LangSmithSandbox
from langgraph.config import get_config


def get_or_create_sandbox_for_thread(thread_id: str) -> LangSmithSandbox:
    if not thread_id:
        raise ValueError("thread_id is required")
    # Look up sandbox_id from thread metadata, create if missing, and seed files.
    raise NotImplementedError(
        "Implement sandbox lookup and creation for your deployment environment."
    )


def get_thread_id_from_config() -> str:
    configurable = get_config().get("configurable", {})
    thread_id = configurable.get("thread_id")
    if not thread_id:
        raise ValueError("No thread_id, agent must run on a thread")
    return thread_id


def agent():
    return create_deep_agent(
        model="openai:gpt-5.5",
        backend=lambda _runtime: get_or_create_sandbox_for_thread(
            get_thread_id_from_config()
        ),
    )

from deepagents import create_deep_agent
from deepagents.backends.langsmith import LangSmithSandbox
from langgraph.config import get_config


def get_or_create_sandbox_for_thread(thread_id: str) -> LangSmithSandbox:
    if not thread_id:
        raise ValueError("thread_id is required")
    # Look up sandbox_id from thread metadata, create if missing, and seed files.
    raise NotImplementedError(
        "Implement sandbox lookup and creation for your deployment environment."
    )


def get_thread_id_from_config() -> str:
    configurable = get_config().get("configurable", {})
    thread_id = configurable.get("thread_id")
    if not thread_id:
        raise ValueError("No thread_id, agent must run on a thread")
    return thread_id


def agent():
    return create_deep_agent(
        model="anthropic:claude-sonnet-4-6",
        backend=lambda _runtime: get_or_create_sandbox_for_thread(
            get_thread_id_from_config()
        ),
    )

from deepagents import create_deep_agent
from deepagents.backends.langsmith import LangSmithSandbox
from langgraph.config import get_config


def get_or_create_sandbox_for_thread(thread_id: str) -> LangSmithSandbox:
    if not thread_id:
        raise ValueError("thread_id is required")
    # Look up sandbox_id from thread metadata, create if missing, and seed files.
    raise NotImplementedError(
        "Implement sandbox lookup and creation for your deployment environment."
    )


def get_thread_id_from_config() -> str:
    configurable = get_config().get("configurable", {})
    thread_id = configurable.get("thread_id")
    if not thread_id:
        raise ValueError("No thread_id, agent must run on a thread")
    return thread_id


def agent():
    return create_deep_agent(
        model="openrouter:z-ai/glm-5.2",
        backend=lambda _runtime: get_or_create_sandbox_for_thread(
            get_thread_id_from_config()
        ),
    )

from deepagents import create_deep_agent
from deepagents.backends.langsmith import LangSmithSandbox
from langgraph.config import get_config


def get_or_create_sandbox_for_thread(thread_id: str) -> LangSmithSandbox:
    if not thread_id:
        raise ValueError("thread_id is required")
    # Look up sandbox_id from thread metadata, create if missing, and seed files.
    raise NotImplementedError(
        "Implement sandbox lookup and creation for your deployment environment."
    )


def get_thread_id_from_config() -> str:
    configurable = get_config().get("configurable", {})
    thread_id = configurable.get("thread_id")
    if not thread_id:
        raise ValueError("No thread_id, agent must run on a thread")
    return thread_id


def agent():
    return create_deep_agent(
        model="fireworks:accounts/fireworks/models/glm-5p2",
        backend=lambda _runtime: get_or_create_sandbox_for_thread(
            get_thread_id_from_config()
        ),
    )

from deepagents import create_deep_agent
from deepagents.backends.langsmith import LangSmithSandbox
from langgraph.config import get_config


def get_or_create_sandbox_for_thread(thread_id: str) -> LangSmithSandbox:
    if not thread_id:
        raise ValueError("thread_id is required")
    # Look up sandbox_id from thread metadata, create if missing, and seed files.
    raise NotImplementedError(
        "Implement sandbox lookup and creation for your deployment environment."
    )


def get_thread_id_from_config() -> str:
    configurable = get_config().get("configurable", {})
    thread_id = configurable.get("thread_id")
    if not thread_id:
        raise ValueError("No thread_id, agent must run on a thread")
    return thread_id


def agent():
    return create_deep_agent(
        model="baseten:zai-org/GLM-5.2",
        backend=lambda _runtime: get_or_create_sandbox_for_thread(
            get_thread_id_from_config()
        ),
    )

from deepagents import create_deep_agent
from deepagents.backends.langsmith import LangSmithSandbox
from langgraph.config import get_config


def get_or_create_sandbox_for_thread(thread_id: str) -> LangSmithSandbox:
    if not thread_id:
        raise ValueError("thread_id is required")
    # Look up sandbox_id from thread metadata, create if missing, and seed files.
    raise NotImplementedError(
        "Implement sandbox lookup and creation for your deployment environment."
    )


def get_thread_id_from_config() -> str:
    configurable = get_config().get("configurable", {})
    thread_id = configurable.get("thread_id")
    if not thread_id:
        raise ValueError("No thread_id, agent must run on a thread")
    return thread_id


def agent():
    return create_deep_agent(
        model="ollama:north-mini-code-1.0",
        backend=lambda _runtime: get_or_create_sandbox_for_thread(
            get_thread_id_from_config()
        ),
    )

Similar to the example in Going to production, the agent is an async graph factory invoked on each run. Store the sandbox ID on thread metadata so custom http.app routes can call the same getOrCreateSandboxForThread helper. Going to production uses provider label lookup instead when the LangGraph SDK is the only entry point.

Seed project files

Before the agent runs, upload starter files with uploadFiles / upload_files. See File transfers for seeding patterns, provider examples, and syncing memories or skills into the sandbox. For LangSmith sandboxes, pass templateName from a sandbox snapshot when creating the container.

Run sandbox.execute("cd /app && npm install") after uploading package.json so dependencies are ready before the first agent turn.

Adding the file browsing API

The agent can read and write files, but the frontend also needs direct access to browse the sandbox filesystem. Add a custom FastAPI API server and expose it through the http.app field in langgraph.json.

Create the API server

The sandbox API endpoints use the thread ID as a URL path parameter. This ensures the frontend always accesses the correct sandbox for the current conversation, using the same get_or_create_sandbox_for_thread function as the agent’s backend:

# src/api/server.py
from fastapi import FastAPI, Query, Path
from utils import get_or_create_sandbox_for_thread

app = FastAPI()

@app.get("/sandbox/{thread_id}/tree")
async def list_tree(
    thread_id: str = Path(...),
    filePath: str = Query("/app"),
):
    sandbox = await get_or_create_sandbox_for_thread(thread_id)
    result = await sandbox.aexecute(
        f"find {filePath} -printf '%y\\t%s\\t%p\\n' 2>/dev/null | sort"
    )
    entries = []
    for line in result.output.strip().split("\n"):
        if not line:
            continue
        type_char, size_str, full_path = line.split("\t")
        entries.append({
            "name": full_path.split("/")[-1],
            "type": "directory" if type_char == "d" else "file",
            "path": full_path,
            "size": int(size_str),
        })
    return {"path": filePath, "entries": entries, "sandboxId": sandbox.id}

@app.get("/sandbox/{thread_id}/file")
async def read_file(
    thread_id: str = Path(...),
    filePath: str = Query(...),
):
    sandbox = await get_or_create_sandbox_for_thread(thread_id)
    results = await sandbox.adownload_files([filePath])
    return {"path": filePath, "content": results[0].content.decode()}

Both the agent’s backend and the API server call the same get_or_create_sandbox_for_thread function. This ensures they always resolveto the same sandbox for a given thread. The sandbox ID in thread metadata is the single source of truth — no in-memory caches needed.

Configure `langgraph.json`

Register both the agent graph and the API server. The http.app field tells the LangGraph platform to serve your custom routes alongside the default ones. See application structure and LangSmith Deployments for the full set of langgraph.json options.

{
  "graphs": {
    "deep_agent_ide": "./src/agents/my_agent.py:agent"
  },
  "env": ".env",
  "http": {
    "app": "./src/api/server.py:app"
  }
}

Your custom routes are available at the same host as the LangGraph API. For local development with langgraph dev, that’s http://localhost:2024.

Custom routes defined in http.app take priority over default LangGraph routes. This means you can shadow built-in endpoints if needed, but be careful not to accidentally override routes like /threads or /runs.

Building the frontend

The frontend has three panels: a file tree sidebar, a code/diff viewer, and a chat panel. It uses useStream for the agent conversation and the custom API endpoints for file browsing. For production deployment, point apiUrl at your LangSmith Deployment, and pass a stable thread_id on each run. See Frontend in Going to production for those settings and for invoking the agent with thread_id and runtime context.

Thread creation

Create a LangGraph thread when the page loads and persist its ID in sessionStorage so page reloads reconnect to the same sandbox:

const THREAD_KEY = "sandbox-thread-id";

function IDEPreview() {
  const [threadId, setThreadId] = useState<string | null>(
    () => sessionStorage.getItem(THREAD_KEY),
  );

  const updateThreadId = useCallback((id: string | null) => {
    setThreadId(id);
    if (id) sessionStorage.setItem(THREAD_KEY, id);
    else sessionStorage.removeItem(THREAD_KEY);
  }, []);

  const stream = useStream<typeof myAgent>({
    apiUrl: AGENT_URL,
    assistantId: "deep_agent_ide",
    threadId,
    onThreadId: updateThreadId,
  });

  // Create thread on first mount
  useEffect(() => {
    if (threadId) return;
    stream.client.threads.create().then((t) => updateThreadId(t.thread_id));
  }, [stream.client, threadId, updateThreadId]);

  // Pass threadId to sandbox file hooks
  const { tree, files } = useSandboxFiles(threadId);
  // ...
}

The “new thread” button clears the stored ID so the next mount creates a fresh thread (and sandbox):

function handleNewThread() {
  updateThreadId(null);
}

File state management

Track two snapshots of the sandbox filesystem: the original state (before the agent runs) and the current state (updated in real time). The thread ID is included in the API URL so requests always hit the correct sandbox:

const AGENT_URL = "http://localhost:2024";

async function fetchTree(threadId: string): Promise<FileEntry[]> {
  const res = await fetch(
    `${AGENT_URL}/sandbox/${encodeURIComponent(threadId)}/tree?filePath=/app`,
  );
  const data = await res.json();
  return data.entries.filter((e: FileEntry) => !e.path.includes("node_modules"));
}

async function fetchFile(threadId: string, path: string): Promise<string | null> {
  const res = await fetch(
    `${AGENT_URL}/sandbox/${encodeURIComponent(threadId)}/file?filePath=${encodeURIComponent(path)}`,
  );
  const data = await res.json();
  return data.content ?? null;
}

Real-time file sync

The key to the IDE experience is updating files as the agent works, not after it finishes. Watch the stream’s messages for ToolMessage instances from file-mutating tools. When a write_file or edit_file tool call completes, refresh that specific file. When execute completes, refresh everything (since a shell command could modify any file):

import { useStream } from "@langchain/react";
import { ToolMessage, AIMessage } from "langchain";

const FILE_MUTATING_TOOLS = new Set(["write_file", "edit_file", "execute"]);

export function IDEPreview() {
  const stream = useStream<typeof myAgent>({
    apiUrl: AGENT_URL,
    assistantId: "deep_agent_ide",
  });

  const processedIds = useRef(new Set<string>());

  useEffect(() => {
    // Build a map of file-mutating tool calls from AI messages
    const toolCallMap = new Map();
    for (const msg of stream.messages) {
      if (!AIMessage.isInstance(msg)) continue;
      for (const tc of msg.tool_calls ?? []) {
        if (tc.id && FILE_MUTATING_TOOLS.has(tc.name)) {
          toolCallMap.set(tc.id, { name: tc.name, args: tc.args });
        }
      }
    }

    // When a ToolMessage appears for a file-mutating tool, refresh
    for (const msg of stream.messages) {
      if (!ToolMessage.isInstance(msg)) continue;
      const id = msg.id ?? msg.tool_call_id;
      if (!id || processedIds.current.has(id)) continue;

      const call = toolCallMap.get(msg.tool_call_id);
      if (!call) continue;
      processedIds.current.add(id);

      if (call.name === "write_file" || call.name === "edit_file") {
        refreshSingleFile(call.args.path ?? call.args.file_path);
      } else if (call.name === "execute") {
        refreshTreeAndFiles();
      }
    }
  }, [stream.messages]);
}

<script setup lang="ts">
import { useStream } from "@langchain/vue";
import { ToolMessage, AIMessage } from "langchain";
import { watch } from "vue";

const FILE_MUTATING_TOOLS = new Set(["write_file", "edit_file", "execute"]);
const processedIds = new Set<string>();

const stream = useStream<typeof myAgent>({
  apiUrl: AGENT_URL,
  assistantId: "deep_agent_ide",
});

watch(
  () => stream.messages.value,
  (messages) => {
    const toolCallMap = new Map();
    for (const msg of messages) {
      if (AIMessage.isInstance(msg)) {
        for (const tc of msg.tool_calls ?? []) {
          if (tc.id && FILE_MUTATING_TOOLS.has(tc.name)) {
            toolCallMap.set(tc.id, { name: tc.name, args: tc.args });
          }
        }
      }
    }

    for (const msg of messages) {
      if (!ToolMessage.isInstance(msg)) continue;
      const id = msg.id ?? msg.tool_call_id;
      if (!id || processedIds.has(id)) continue;

      const call = toolCallMap.get(msg.tool_call_id);
      if (!call) continue;
      processedIds.add(id);

      if (call.name === "write_file" || call.name === "edit_file") {
        refreshSingleFile(call.args.path ?? call.args.file_path);
      } else if (call.name === "execute") {
        refreshTreeAndFiles();
      }
    }
  },
  { deep: true },
);
</script>

<script lang="ts">
  import { useStream } from "@langchain/svelte";
  import { ToolMessage, AIMessage } from "langchain";

  const FILE_MUTATING_TOOLS = new Set(["write_file", "edit_file", "execute"]);
  const processedIds = new Set<string>();

  const stream = useStream<typeof myAgent>({
    apiUrl: AGENT_URL,
    assistantId: "deep_agent_ide",
  });

  $effect(() => {
    const msgs = stream.messages;
    const toolCallMap = new Map();
    for (const msg of msgs) {
      if (AIMessage.isInstance(msg)) {
        for (const tc of msg.tool_calls ?? []) {
          if (tc.id && FILE_MUTATING_TOOLS.has(tc.name)) {
            toolCallMap.set(tc.id, { name: tc.name, args: tc.args });
          }
        }
      }
    }

    for (const msg of msgs) {
      if (!ToolMessage.isInstance(msg)) continue;
      const id = msg.id ?? msg.tool_call_id;
      if (!id || processedIds.has(id)) continue;

      const call = toolCallMap.get(msg.tool_call_id);
      if (!call) continue;
      processedIds.add(id);

      if (call.name === "write_file" || call.name === "edit_file") {
        refreshSingleFile(call.args.path ?? call.args.file_path);
      } else if (call.name === "execute") {
        refreshTreeAndFiles();
      }
    }
  });
</script>

import { Component, effect } from "@angular/core";
import { injectStream } from "@langchain/angular";
import { ToolMessage, AIMessage } from "langchain";

const FILE_MUTATING_TOOLS = new Set(["write_file", "edit_file", "execute"]);

@Component({
  selector: "app-ide-preview",
  template: `<!-- ... -->`,
})
export class IdePreviewComponent {
  stream = injectStream<typeof myAgent>({
    apiUrl: AGENT_URL,
    assistantId: "deep_agent_ide",
  });

  private processedIds = new Set<string>();

  constructor() {
    effect(() => {
      const messages = this.stream.messages();
      const toolCallMap = new Map();
      for (const msg of messages) {
        if (AIMessage.isInstance(msg)) {
          for (const tc of (msg as AIMessage).tool_calls ?? []) {
            if (tc.id && FILE_MUTATING_TOOLS.has(tc.name)) {
              toolCallMap.set(tc.id, { name: tc.name, args: tc.args });
            }
          }
        }
      }

      for (const msg of messages) {
        if (!ToolMessage.isInstance(msg)) continue;
        const id = (msg as ToolMessage).id ?? (msg as ToolMessage).tool_call_id;
        if (!id || this.processedIds.has(id)) continue;

        const call = toolCallMap.get((msg as ToolMessage).tool_call_id);
        if (!call) continue;
        this.processedIds.add(id);

        if (call.name === "write_file" || call.name === "edit_file") {
          this.refreshSingleFile(call.args.path ?? call.args.file_path);
        } else if (call.name === "execute") {
          this.refreshTreeAndFiles();
        }
      }
    });
  }
}

Detecting changed files

Before each agent run, snapshot the current file contents. After files refresh, compare against the snapshot to identify which files changed:

function detectChanges(current: FileSnapshot, original: FileSnapshot): Set<string> {
  const changed = new Set<string>();
  for (const [path, content] of Object.entries(current)) {
    if (original[path] !== content) changed.add(path);
  }
  for (const path of Object.keys(original)) {
    if (!(path in current)) changed.add(path);
  }
  return changed;
}

When a user selects a changed file, default to the diff view so they immediately see what the agent modified.

Displaying diffs

Use a framework-appropriate diff library to render unified diffs:

Framework	Library	Component
React	`@pierre/diffs`	`<FileDiff>` with `parseDiffFromFile`
Vue	`@git-diff-view/vue`	`<DiffView>` with `generateDiffFile` from `@git-diff-view/file`
Svelte	`@git-diff-view/svelte`	`<DiffView>` with `generateDiffFile` from `@git-diff-view/file`
Angular	`ngx-diff`	`<ngx-unified-diff>` with `[before]` and `[after]`

Example with @pierre/diffs (React):

import { FileDiff } from "@pierre/diffs/react";
import { parseDiffFromFile } from "@pierre/diffs";

function DiffPanel({ original, current, fileName }) {
  const diff = parseDiffFromFile(
    { name: fileName, contents: original },
    { name: fileName, contents: current },
  );

  return (
    <FileDiff
      fileDiff={diff}
      options={{ theme: "github-dark", diffStyle: "unified", diffIndicators: "bars" }}
    />
  );
}

Changed files summary

Show a summary of all modified files with line-level addition/deletion counts. This gives users a quick overview of the agent’s impact — similar to a git status:

function ChangedFilesSummary({ changedFiles, files, originalFiles, onSelect }) {
  const stats = [...changedFiles].map((path) => {
    const oldLines = (originalFiles[path] ?? "").split("\n");
    const newLines = (files[path] ?? "").split("\n");
    // Compute additions/deletions by comparing lines
    return { path, additions, deletions };
  });

  return (
    <div>
      <h3>{stats.length} Files Changed</h3>
      {stats.map((file) => (
        <button key={file.path} onClick={() => onSelect(file.path)}>
          {file.path}
          <span className="text-green-400">+{file.additions}</span>
          <span className="text-red-400">-{file.deletions}</span>
        </button>
      ))}
    </div>
  );
}

Use cases

A sandbox is the right choice when:

Coding agents that create, modify, and run code need a visual interface beyond chat
Code review workflows where the agent suggests changes and the user reviews diffs before accepting
Tutorial or learning apps where an AI assistant helps users build a project step by step, showing changes in context
Prototyping tools where users describe features in natural language and watch the agent implement them in real time

Best practices

Frontend-specific:

Persist threadId in sessionStorage so page reloads reconnect to the same thread and sandbox instead of creating new ones.
Sync files on every relevant tool call, not just when the run finishes. Watch for write_file, edit_file, and execute tool messages and refresh immediately.
Default to diff view for changed files. When a user clicks a file that was modified by the agent, show the diff first — that’s what they care about.
Show compact tool results for read-only operations. Instead of dumping the full output of read_file in the chat, show a one-liner like Read router.js L1-42. Reserve the full output display for mutating tools.
Filter node_modules from the file tree. Nobody wants to browse thousands of dependency files. Filter them out when fetching the tree.

For backends and sandboxes:

Use thread-scoped sandboxes for production apps. See Sandbox lifecycle.
Share sandbox resolution between the agent backend and the API server via thread metadata so both resolve the same environment with no in-memory caches.
Seed the sandbox with a real project. See File transfers.
Keep secrets out of the sandbox. Use the sandbox auth proxy instead of environment variables or file uploads for API keys.
Add guardrails before launch. Configure rate limits, error handling, and data privacy middleware for autonomous coding agents.

Going to production

Deploy the agent with persistent sandboxes, auth, guardrails, and production useStream settings.

Sandboxes

Sandbox providers, security model, and file transfer APIs.

Frontend overview

Other deep agent UI patterns: subagent streaming, todo lists, and custom state.

Application structure

Full langgraph.json reference, including custom http.app routes.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

​Architecture

​Sandbox lifecycle

​Connect the agent and API server

​Resolve the sandbox from thread metadata

​Seed project files

​Adding the file browsing API

​Create the API server

​Configure langgraph.json

​Building the frontend

​Thread creation

​File state management

​Real-time file sync

​Detecting changed files

​Displaying diffs

​Changed files summary

​Use cases

​Best practices

​Related

Going to production

Sandboxes

Frontend overview

Application structure

Architecture

Sandbox lifecycle

Connect the agent and API server

Resolve the sandbox from thread metadata

Seed project files

Adding the file browsing API

Create the API server

Configure `langgraph.json`

Building the frontend

Thread creation

File state management

Real-time file sync

Detecting changed files

Displaying diffs

Changed files summary

Use cases

Best practices

Related