Sandboxes

• 所有 standard filesystem tools（ls、read_file、write_file、edit_file、glob、grep）
• 用于在 sandbox 中运行 arbitrary shell commands 的 execute tool
• 保护 host system 的 secure boundary

​

Why use sandboxes?

• Coding agents：Autonomously 运行的 agents 可以使用 shell、git、clone repositories（许多 providers 提供 native git APIs，例如 Daytona’s git operations），并为 build 和 test pipelines 运行 Docker-in-Docker
• Data analysis agents：在 safe、isolated environment 中 load files、install data analysis libraries（pandas、numpy 等）、运行 statistical calculations，并创建 PowerPoint presentations 等 outputs

​

Basic usage

import { createDeepAgent } from "deepagents";
import { ChatAnthropic } from "@langchain/anthropic";
import { DenoSandbox } from "@langchain/deno";

// Create and initialize the sandbox
const sandbox = await DenoSandbox.create({
  memoryMb: 1024,
  lifetime: "10m",
});

try {
  const agent = createDeepAgent({
    model: new ChatAnthropic({ model: "claude-opus-4-6" }),
    systemPrompt: "You are a JavaScript coding assistant with sandbox access.",
    backend: sandbox,
  });

  const result = await agent.invoke({
    messages: [
      {
        role: "user",
        content:
          "Create a simple HTTP server using Deno.serve and test it with curl",
      },
    ],
  });
} finally {
  await sandbox.close();
}

​

Available providers

ModalDaytonaDenoNode VFSLangSmith

​

Lifecycle and scoping

​

Thread-scoped (default)

from daytona import CreateSandboxFromSnapshotParams, Daytona
from deepagents import create_deep_agent
from langchain_core.runnables import RunnableConfig
from langchain_daytona import DaytonaSandbox

client = Daytona()


async def agent(config: RunnableConfig):
    thread_id = config["configurable"]["thread_id"]
    try:
        sandbox = await client.find_one(labels={"thread_id": thread_id})
    except Exception:
        sandbox = await client.create(
            CreateSandboxFromSnapshotParams(
                labels={"thread_id": thread_id},
                auto_delete_interval=3600,  # TTL: clean up when idle
            )
        )
    return create_deep_agent(
        model="google_genai:gemini-3.5-flash",
        backend=DaytonaSandbox(sandbox=sandbox)
    )

import { Daytona } from "@daytonaio/sdk";
import { DaytonaSandbox } from "@langchain/daytona";
import { createDeepAgent } from "deepagents";
import type { LangGraphRunnableConfig } from "@langchain/langgraph";

const client = new Daytona();

export async function agent(config: LangGraphRunnableConfig) {
  const threadId = config.configurable?.thread_id as string;
  let sandbox;
  try {
    sandbox = await client.findOne({ labels: { thread_id: threadId } });
  } catch {
    sandbox = await client.create({
      labels: { thread_id: threadId },
      autoDeleteInterval: 3600, // TTL: clean up when idle
    });
  }
  return createDeepAgent({
    model: "google_genai:gemini-3.5-flash",
    backend: await DaytonaSandbox.fromId(sandbox.id),
  });
}

​

Assistant-scoped

from daytona import CreateSandboxFromSnapshotParams, Daytona
from deepagents import create_deep_agent
from langchain_core.runnables import RunnableConfig
from langchain_daytona import DaytonaSandbox

client = Daytona()


async def agent(config: RunnableConfig):
    assistant_id = config["configurable"]["assistant_id"]
    try:
        sandbox = await client.find_one(labels={"assistant_id": assistant_id})
    except Exception:
        sandbox = await client.create(
            CreateSandboxFromSnapshotParams(labels={"assistant_id": assistant_id})
        )
    return create_deep_agent(
        model="google_genai:gemini-3.5-flash",
        backend=DaytonaSandbox(sandbox=sandbox)
    )

import { Daytona } from "@daytonaio/sdk";
import { DaytonaSandbox } from "@langchain/daytona";
import { createDeepAgent } from "deepagents";
import type { LangGraphRunnableConfig } from "@langchain/langgraph";

const client = new Daytona();

export async function agent(config: LangGraphRunnableConfig) {
  const assistantId = config.configurable?.assistant_id as string;
  let sandbox;
  try {
    sandbox = await client.findOne({ labels: { assistant_id: assistantId } });
  } catch {
    sandbox = await client.create({ labels: { assistant_id: assistantId } });
  }
  return createDeepAgent({
    model: "google_genai:gemini-3.5-flash",
    backend: await DaytonaSandbox.fromId(sandbox.id),
  });
}

​

Integration patterns

​

Agent in sandbox pattern

• ✅ 与 local development 高度一致。
• ✅ Agent 与 environment 紧密耦合。

• 🔴 API keys 必须存在于 sandbox 内（security risk）。
• 🔴 Updates 需要 rebuild images。
• 🔴 需要 communication infrastructure（WebSocket 或 HTTP layer）。

FROM python:3.11
RUN pip install deepagents-code

​

Sandbox as tool pattern

• ✅ 无需 rebuilding images 即可即时 update agent code。
• ✅ Agent state 和 execution 之间有更清晰的 separation。
  • API keys 保留在 sandbox 外。
  • Sandbox failures 不会丢失 agent state。
  • 可以选择在多个 sandboxes 中 parallel 运行 tasks。
• ✅ 只为 execution time 付费。

• 🔴 每次 execution call 都有 network latency。

import "dotenv/config";
import { DaytonaSandbox } from "@langchain/daytona";
import { createDeepAgent } from "deepagents";

// Can also do this with E2B, Runloop, Modal
const sandbox = await DaytonaSandbox.create();

const agent = createDeepAgent({
  backend: sandbox,
  systemPrompt:
    "You are a coding assistant with sandbox access. You can create and run code in the sandbox.",
});

try {
  const result = await agent.invoke({
    messages: [
      {
        role: "user",
        content: "Create a hello world Python script and run it",
      },
    ],
  });
  const lastMessage = result.messages[result.messages.length - 1];
  console.log(
    typeof lastMessage.content === "string"
      ? lastMessage.content
      : String(lastMessage.content),
  );
} catch (err) {
  // Optional: delete the sandbox proactively on an exception
  await sandbox.close();
  throw err;
}

​

How sandboxes work

​

Isolation boundaries

• Context injection：控制 agent input 一部分的 attacker 可以指示它在 sandbox 内运行 arbitrary commands。Sandbox 是 isolated，但 agent 在其中拥有 full control。
• Network exfiltration：除非 block network access，否则被 context-injected 的 agent 可以通过 HTTP 或 DNS 将 data 发送到 sandbox 外。某些 providers 支持 blocking network access（例如 Modal 上的 blockNetwork: true）。

​

The execute method

• 添加 new provider 很直接。 实现 execute()，base class 会处理其他所有内容。
• execute tool 是 conditionally available。 每次 model call 时，harness 都会检查 backend 是否实现 SandboxBackendProtocol。如果没有，该 tool 会被 filter out，agent 永远不会看到它。

4
[Command succeeded with exit code 0]

bash: foobar: command not found
[Command failed with exit code 127]

​

Two planes of file access

• Seed the sandbox：在 agent 运行前放入 source code、configuration 或 data
• Retrieve artifacts：在 agent 完成后取回 generated code、build outputs、reports
• Pre-populate dependencies：预先放入 agent 将需要的 dependencies

​

Working with files

​

Seeding the sandbox

const encoder = new TextEncoder();
const responses = await sandbox.uploadFiles([
  ["src/index.js", encoder.encode("console.log('Hello')")],
  ["package.json", encoder.encode('{"name": "my-app"}')],
]);

// Each response indicates success or failure
for (const res of responses) {
  if (res.error) {
    console.error(`Failed to upload ${res.path}: ${res.error}`);
  }
}

​

Retrieving artifacts

const results = await sandbox.downloadFiles(["src/index.js", "output.txt"]);

const decoder = new TextDecoder();
for (const result of results) {
  if (result.content) {
    console.log(`${result.path}: ${decoder.decode(result.content)}`);
  } else {
    console.error(`Failed to download ${result.path}: ${result.error}`);
  }
}

​

Security considerations

​

Handling secrets safely

1. 将 secrets 保留在 sandbox 外部的 tools 中。 定义在 host environment（不是 sandbox 内）运行的 tools，并在那里处理 authentication。Agent 按 name 调用这些 tools，但永远看不到 credentials。这是推荐方法。
2. 使用注入 credentials 的 network proxy。 某些 sandbox providers 支持 proxies，它们会拦截 sandbox 发出的 outgoing HTTP requests，并在转发前附加 credentials（例如 Authorization headers）。Agent 永远看不到 secret，它只向 URL 发出 plain requests。此方法尚未在 providers 间广泛可用。

​

General best practices

• 在 application 中使用 sandbox outputs 前先 review
• 不需要 network access 时 block sandbox network access
• 使用 middleware filter 或 redact tool outputs 中的 sensitive patterns
• 将 sandbox 内生成的一切视为 untrusted input