Node VFS

Node VFS

deepagents와 함께 Node.js VFS 샌드박스 백엔드를 사용하면 로컬 개발과 테스트가 가능해요.

VFS 샌드박스는 인메모리 가상 파일 시스템을 사용해 완전히 로컬에서 실행돼요. 클라우드 서비스, Docker, 외부 의존성이 필요 없어 개발과 테스트에 완벽합니다.

node-vfs-polyfill을 사용하는데, 이는 곧 제공될 Node.js VFS 기능(nodejs/node#61478)을 구현합니다.

출처: 문서

본문

설정

npm install @langchain/node-vfs

yarn add @langchain/node-vfs

pnpm add @langchain/node-vfs

인증이 필요하지 않습니다.

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)

작동 방식(How it works)

VFS는 최대 호환성을 위해 하이브리드 접근 방식을 사용합니다:

1. 파일 저장: 파일은 가상 파일 시스템을 사용해 인메모리로 저장됨
2. 명령 실행: 명령 실행 시 파일이 임시 디렉터리에 동기화되고, 명령이 실행된 후 변경 사항이 VFS로 다시 동기화됨
3. 폴백 모드: node-vfs-polyfill을 사용할 수 없으면 저장과 실행 모두 임시 디렉터리를 사용하도록 폴백

이는 완전한 셸 명령 실행 지원을 유지하면서 인메모리 저장(격리, 속도)의 이점을 제공합니다.

파일 작업(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)

VFS를 사용해야 할 때(When to use VFS)

가장 적합한 경우:

• 로컬 개발과 테스트
• Docker 없는 CI/CD 파이프라인
• 클라우드 설정 없는 빠른 프로토타이핑
• 외부 서비스를 사용할 수 없는 환경

적합하지 않은 경우:

• 실제 컨테이너 격리가 필요한 프로덕션 워크로드
• 세션 간 영속적 저장
• 무거운 컴퓨팅 작업(리소스 제한 없음)

미래: 네이티브 Node.js VFS

이 패키지는 nodejs/node#61478에서 개발 중인 곧 제공될 Node.js VFS 기능을 구현하는 node-vfs-polyfill을 사용합니다. 공식 node:vfs 모듈이 Node.js에 포함되면 이 패키지는 네이티브 구현을 사용하도록 업데이트될 것입니다.

더 알아보기 (Learn more)

• node-vfs-polyfill

• 이 문서를 MCP로 연결하면 Claude, VSCode 등에서 실시간 답변을 받을 수 있어요.
• GitHub에서 이 페이지 편집하기 또는 이슈 제출하기.