Skip to main content
The VFS sandbox runs entirely locally using an in-memory virtual file system. No cloud services, Docker, or external dependencies required - perfect for development and testing. It uses node-vfs-polyfill which implements the upcoming Node.js VFS feature (nodejs/node#61478).

​
Setup

npm install @langchain/node-vfs
No authentication required.

​
Usage with deepagents

import { createDeepAgent } from "deepagents";
import { ChatAnthropic } from "@langchain/anthropic";
import { VfsSandbox } from "@langchain/node-vfs";

const sandbox = await VfsSandbox.create({
  initialFiles: {
    "/src/index.js": "console.log('Hello from VFS!')",
  },
});

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

  const result = await agent.invoke({
    messages: [{ role: "user", content: "Run the index.js file" }],
  });
} finally {
  await sandbox.stop();
}

​
Standalone usage

import { VfsSandbox } from "@langchain/node-vfs";

const sandbox = await VfsSandbox.create({
  initialFiles: {
    "/src/index.js": "console.log('Hello from VFS!')",
  },
});

const result = await sandbox.execute("node /src/index.js");
console.log(result.output); // "Hello from VFS!"

await sandbox.stop();

​
Configuration

OptionTypeDefaultDescription
mountPathstring"/vfs"Mount path for the virtual file system
timeoutnumber30000Command execution timeout in milliseconds
initialFilesRecord<string, string | Uint8Array>-Initial files to populate the VFS

​
How it works

VFS uses a hybrid approach for maximum compatibility:
  1. File storage: Files are stored in-memory using a virtual file system
  2. Command execution: When executing commands, files sync to a temp directory, the command runs, and changes sync back to VFS
  3. Fallback mode: If node-vfs-polyfill is unavailable, falls back to using a temp directory for both storage and execution
This provides the benefits of in-memory storage (isolation, speed) while maintaining full shell command execution support.

​
File operations

// Upload files
const encoder = new TextEncoder();
await sandbox.uploadFiles([
  ["src/app.js", encoder.encode("console.log('Hi')")],
  ["package.json", encoder.encode('{"name": "test"}')],
]);

// Download files
const results = await sandbox.downloadFiles(["src/app.js"]);
for (const result of results) {
  if (result.content) {
    console.log(new TextDecoder().decode(result.content));
  }
}

​
Factory functions

import { createVfsSandboxFactory, createVfsSandboxFactoryFromSandbox } from "@langchain/node-vfs";

// Create new sandbox per invocation
const factory = createVfsSandboxFactory({
  initialFiles: { "/README.md": "# Hello" },
});

// Or reuse an existing sandbox across invocations
const sandbox = await VfsSandbox.create();
const reuseFactory = createVfsSandboxFactoryFromSandbox(sandbox);

​
Error handling

import { VfsSandboxError } from "@langchain/node-vfs";

try {
  await sandbox.execute("some-command");
} catch (error) {
  if (error instanceof VfsSandboxError) {
    switch (error.code) {
      case "NOT_INITIALIZED":
        // Handle uninitialized sandbox
        break;
      case "COMMAND_TIMEOUT":
        // Handle timeout
        break;
    }
  }
}

​
Error codes

CodeDescription
NOT_INITIALIZEDSandbox not initialized
ALREADY_INITIALIZEDSandbox already initialized
INITIALIZATION_FAILEDFailed to initialize VFS
COMMAND_TIMEOUTCommand execution timed out
COMMAND_FAILEDCommand execution failed
FILE_OPERATION_FAILEDFile operation failed
NOT_SUPPORTEDVFS not supported in environment

​
When to use VFS

Best suited for:
  • Local development and testing
  • CI/CD pipelines without Docker
  • Quick prototyping without cloud setup
  • Environments where external services aren’t available
Not ideal for:
  • Production workloads requiring true container isolation
  • Persistent storage across sessions
  • Heavy computational tasks (no resource limits)

​
Future: Native Node.js VFS

This package uses node-vfs-polyfill which implements the upcoming Node.js VFS feature being developed in nodejs/node#61478. When the official node:vfs module lands in Node.js, this package will be updated to use the native implementation.
Edit this page on GitHub or file an issue.
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.