@langchain/deno

Deno Sandbox backend for deepagents. This package provides a DenoSandbox implementation of the SandboxBackendProtocol, enabling agents to execute commands, read/write files, and manage isolated Linux microVM environments using Deno Deploy's Sandbox infrastructure.

Features

• Isolated Execution: Run commands in secure, isolated Linux microVMs
• File Operations: Upload and download files with full filesystem access
• BaseSandbox Integration: All inherited methods (read, write, edit, ls, grep, glob) work out of the box
• Factory Pattern: Compatible with deepagents' middleware architecture
• Full SDK Access: Access the underlying Deno SDK via the sandbox property for advanced features

Installation

# npm
npm install @langchain/deno

# yarn
yarn add @langchain/deno

# pnpm
pnpm add @langchain/deno

Authentication Setup

The package requires Deno Deploy authentication:

Environment Variable (Recommended)

1. Go to https://app.deno.com
2. Navigate to Settings → Organization Tokens
3. Create a new token and set it as an environment variable:

export DENO_DEPLOY_TOKEN=your_token_here

Explicit Token in Code

const sandbox = await DenoSandbox.create({
  auth: { token: "your-token-here" },
});

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-sonnet-4-20250514" }),
    systemPrompt: "You are a coding assistant with access to a sandbox.",
    backend: sandbox,
  });

  const result = await agent.invoke({
    messages: [
      { role: "user", content: "Create a hello world Deno app and run it" },
    ],
  });
} finally {
  await sandbox.close();
}

Configuration Options

interface DenoSandboxOptions {
  /**
   * Memory allocation in megabytes.
   * Min: 768MB, Max: 4096MB
   * @default 768
   */
  memoryMb?: number;

  /**
   * Sandbox lifetime.
   * - "session": Shuts down when you close the client (default)
   * - Duration: e.g., "5m", "30s"
   */
  lifetime?: "session" | `${number}s` | `${number}m`;

  /**
   * Region where the sandbox will be created.
   * If not specified, uses the default region.
   */
  region?: DenoSandboxRegion;

  /**
   * Authentication configuration.
   */
  auth?: {
    token?: string;
  };
}

Available Regions

The sandbox can be deployed in the following regions:

Region Code	Location
ams	Amsterdam
ord	Chicago

Accessing the Deno SDK

For advanced features not exposed by BaseSandbox, you can access the underlying Deno SDK directly via the sandbox property:

const denoSandbox = await DenoSandbox.create();

// Access the raw Deno SDK
const sdk = denoSandbox.sandbox;

// Use any Deno SDK feature directly
const url = await sdk.exposeHttp({ port: 3000 });
const ssh = await sdk.exposeSsh();
const result = await sdk.eval("1 + 2");
await sdk.env.set("API_KEY", "secret");

// Use shell template literals
const output = await sdk.sh`echo "Hello from Deno!"`.text();

// Start a JavaScript runtime
const runtime = await sdk.createJsRuntime({ entrypoint: "server.ts" });

See the @deno/sandbox documentation for all available SDK methods.

Factory Functions

Creating New Sandboxes Per Invocation

import { createDenoSandboxFactory } from "@langchain/deno";

// Each call creates a new sandbox
const factory = createDenoSandboxFactory({ memoryMb: 1024 });

const sandbox1 = await factory();
const sandbox2 = await factory();

try {
  // Use sandboxes...
} finally {
  await sandbox1.close();
  await sandbox2.close();
}

Reusing an Existing Sandbox

import { createDeepAgent, createFilesystemMiddleware } from "deepagents";
import {
  DenoSandbox,
  createDenoSandboxFactoryFromSandbox,
} from "@langchain/deno";

// Create and initialize a sandbox
const sandbox = await DenoSandbox.create({ memoryMb: 1024 });

try {
  const agent = createDeepAgent({
    model: new ChatAnthropic({ model: "claude-sonnet-4-20250514" }),
    systemPrompt: "You are a coding assistant.",
    middlewares: [
      createFilesystemMiddleware({
        backend: createDenoSandboxFactoryFromSandbox(sandbox),
      }),
    ],
  });

  await agent.invoke({ messages: [...] });
} finally {
  await sandbox.close();
}

Reconnecting to Existing Sandboxes

Resume working with a sandbox that has a duration-based lifetime:

// First session: create with duration lifetime
const sandbox = await DenoSandbox.create({
  memoryMb: 1024,
  lifetime: "30m",
});
const sandboxId = sandbox.id;
await sandbox.close(); // Close connection, but sandbox keeps running

// Later: reconnect to the same sandbox
const reconnected = await DenoSandbox.connect(sandboxId);
const result = await reconnected.execute("ls -la");

Error Handling

import { DenoSandboxError } from "@langchain/deno";

try {
  await sandbox.execute("some command");
} catch (error) {
  if (error instanceof DenoSandboxError) {
    switch (error.code) {
      case "NOT_INITIALIZED":
        await sandbox.initialize();
        break;
      case "COMMAND_TIMEOUT":
        console.error("Command took too long");
        break;
      case "AUTHENTICATION_FAILED":
        console.error("Check your Deno Deploy token");
        break;
      default:
        throw error;
    }
  }
}

Error Codes

Code	Description
NOT_INITIALIZED	Sandbox not initialized - call initialize()
ALREADY_INITIALIZED	Cannot initialize twice
AUTHENTICATION_FAILED	Invalid or missing Deno Deploy token
SANDBOX_CREATION_FAILED	Failed to create sandbox
SANDBOX_NOT_FOUND	Sandbox ID not found or expired
COMMAND_TIMEOUT	Command execution timed out
COMMAND_FAILED	Command execution failed
FILE_OPERATION_FAILED	File read/write failed
RESOURCE_LIMIT_EXCEEDED	CPU, memory, or storage limits exceeded

Inherited BaseSandbox Methods

DenoSandbox extends BaseSandbox and inherits these convenience methods:

Method	Description
read()	Read a file's contents
write()	Write content to a file
edit()	Replace text in a file
lsInfo()	List directory contents
grepRaw()	Search for patterns in files
globInfo()	Find files matching a pattern

Limits and Constraints

Constraint	Value
Minimum memory	768 MB
Maximum memory	4096 MB (4 GB)
Disk space	10 GB
vCPUs	2
Working directory	/home/app
Network access	Full (by default)
Interactive commands	Not supported

Environment Variables

Variable	Description
DENO_DEPLOY_TOKEN	Deno Deploy organization access token

License

MIT