VirtualFS SDKs

The VirtualFS SDKs are hand-written clients for the standalone VirtualFS HTTP server documented in the VirtualFS API Reference. They are separate from the generated Conductor SDKs (orcapods, @agent-orc/..., sdks/go) and they target the /vfs/... HTTP surface directly. Use a VirtualFS SDK when application code needs to:

Read or write files in tenant-scoped mounts from outside the agent runtime.
Run sealed shell commands against the VirtualFS without going through the conductor.
Expose VFS as agent tools to OpenAI, Vercel AI SDK, or Claude SDK loops.
Provide a sandbox-shaped facade to existing agent runtime code.

Package map

The VirtualFS SDKs ship as four packages in this repository:

Package	Path	Language	Role
`agent-orc-vfs`	`virtualfs/sdk/py`	Python	Core `Workspace` client, mount factories, OpenAI function tools
`@agent-orc/vfs`	`virtualfs/sdk/ts`	TypeScript	Core `Workspace` client, mount factories, Vercel AI / OpenAI tools, in-package `SandboxClient`
`@agent-orc/claude-vfs`	`virtualfs/sdk/adapters/claude-sdk`	TypeScript	Claude Messages Bash tool adapter that routes through `Workspace.execute()`
`agent-orc-vfs-openai`	`virtualfs/sdk/adapters/openai-agents`	Python	Virtual sandbox protocol adapter (`SandboxClient`) backed by a `Workspace`

Runnable examples live under virtualfs/examples/python and virtualfs/examples/typescript. There is no Go VirtualFS SDK. Go callers use virtualfs.New(dispatcher, policy) and Workspace.Execute(ctx, cmd, ExecOpts) directly from the in-process Go package documented in the API Reference Workspace Execute section.

Server prerequisites

Every SDK client speaks the structured /vfs/... surface plus POST /vfs/exec. Boot a server before running any SDK example:

go run ./virtualfs/cmd/vfs serve

Defaults:

Standalone serve listens on :8080. The compose-backed VirtualFS service (the vfs service in docker-compose.yml) is reachable at http://localhost:18080 on the host, or at http://vfs:8080 from inside the compose network.
Without VFS_AUTH_TOKEN, the local server uses smokeAuth and accepts a caller-supplied bearer token. Set VFS_AUTH_TOKEN for any non-local deployment.
The smoke driver seeds /s3/log.jsonl and /s3/report.parquet unless --seed=false is passed.

Common environment variables consumed by the SDKs and examples:

Variable	SDK use
`VFS_BASE_URL`	Base URL for the SDK client. `http://localhost:8080` for `vfs serve`, `http://localhost:18080` for the compose `vfs` service on the host (`http://vfs:8080` from inside the compose network).
`VFS_TOKEN`	Bearer token sent as `Authorization: Bearer ${TOKEN}`; set it explicitly for the local smoke server or any deployed server.
`VFS_AUTH_TOKEN`	Server-side env consumed by `vfs serve`; SDK clients should send the same value as `VFS_TOKEN`.

When VirtualFS is fronted by the conductor (/api/vfs/*), client Authorization headers are stripped and the proxy injects Bearer ${VFS_AUTH_TOKEN} server-side (the conductor reads VFS_AUTH_TOKEN directly). When fronted by the Vercel-hosted dashboard (/vfs/* rewrite), Edge middleware injects Bearer ${VFS_TOKEN}, a separate Vercel project env var that must be kept in sync with the Railway vfs service’s VFS_AUTH_TOKEN. In both cases client Authorization headers are stripped and overwritten server-side. The SDK token argument is for direct use against a standalone or Railway-hosted VirtualFS, not for browser code that already routes through one of those proxies.

Python: `agent-orc-vfs`

A thin async + sync HTTP client built on httpx and Pydantic v2.

Install

The package is not yet on PyPI. Install from the repo:

pip install ./virtualfs/sdk/py

For editable development with uv:

cd virtualfs/sdk/py && uv sync

Runtime requirements: Python >=3.11, httpx>=0.27, pydantic>=2.7.

Workspace

Workspace is the entry point. It carries declared mount metadata used by file_prompt and by validate() plus a base URL and bearer token used by every HTTP call.

import os

from agent_orc_vfs import Workspace, ram

ws = Workspace(
    {
        "/": ram(),
    },
    base_url=os.getenv("VFS_BASE_URL", "http://localhost:8080"),
    token=os.environ["VFS_TOKEN"],
)

Constructor signature:

Workspace(
    mounts: dict[str, Mount],
    *,
    base_url: str,
    token: str,
    timeout: float = 30.0,
    file_prompt_template: Callable[[dict[str, Mount]], str] | None = None,
)

Argument	Purpose
`mounts`	Client-side declared mount specs used to render `file_prompt` and by `validate()`. The server owns the live mount table; call `mounts()` for the live data or `validate()` to assert declared specs match server reality. The default prod/dev/disk profiles expose one live mount at `/`; declare non-root paths only for runtime user mounts that exist on the server.
`base_url`	Base URL of the VirtualFS HTTP API. Trailing slash is normalized away.
`token`	Bearer token sent on every request.
`timeout`	Per-request HTTP timeout in seconds.
`file_prompt_template`	Optional callable that receives the mount dict and returns the system-prompt fragment. Defaults to `default_template`.

The instance lazily opens an httpx.AsyncClient and httpx.Client the first time async or sync methods are called. Both close paths are explicit:

ws.close()           # close sync client
await ws.aclose()    # close async client

with ws:             # sync context manager: calls close()
    ws.execute_sync("ls /")

async with ws:       # async context manager: calls aclose()
    await ws.execute("ls /")

Mount factories

Mount specs declare the backend each path is expected to be backed by. The server validates the declaration at connect time via validate().

from agent_orc_vfs import ram, r2

ram()                                                        # ephemeral in-process RAM (dev profile)
r2(bucket="agent-orc-prod")                                  # R2 bucket root
r2(bucket="agent-orc-prod", prefix="kb/")                    # R2 bucket with key prefix
r2(bucket="agent-orc-prod", endpoint="https://<acct>.r2.cloudflarestorage.com")  # explicit endpoint

Both return frozen dataclasses (RamMount, R2Mount). Clients cannot register additional mount kinds; the server is the source of truth for which paths exist. Call validate() (or validate_sync()) to assert that every declared path exists on the server and that its kind, bucket, and endpoint match. See Strict mount validation.

Typed file operations

Every async helper has a sync sibling. All operations target the typed POST /vfs/... endpoints described in the API reference.

Async	Sync	Returns	Notes
`cat(path, *, range_start=0, range_end=0)`	`cat_sync(...)`	`bytes`	Binary-safe; decodes server `text` or `base64` envelope automatically.
`cat_text(path)`	`cat_text_sync(path)`	`str`	UTF-8 convenience wrapper.
`ls(path, *, recursive=False, limit=0, cursor="")`	`ls_sync(...)`	`list[Entry]`
`stat(path)`	`stat_sync(path)`	`Entry`	Raises `NotFound` if the path does not exist.
`find(path, *, name=None, type=None, limit=0)`	`find_sync(...)`	`list[Entry]`	`type` accepts `"file"` or `"dir"`.
`grep(pattern, path, *, recursive=False, regex=False, max_matches=100)`	`grep_sync(...)`	`list[GrepMatch]`
`write(path, content, *, mime=None)`	`write_sync(...)`	`Entry`	`bytes` is sent base64-encoded; `str` is sent as text.
`delete(path, *, recursive=False)`	`delete_sync(...)`	`None`
`mounts()`	`mounts_sync()`	`list[MountInfo]`	Returns the live mount table from `GET /vfs/mounts`.
`validate()`	`validate_sync()`	`None`	Asserts declared mount specs match the server’s live table. Raises `MountMismatch` or `MountUnavailable` on failure.

cat, ls, stat, find, grep, write, delete, and execute all accept an optional session_id keyword argument that scopes the call to a session’s mount allowlist (see Sessions below).

Sessions

Sessions are server-side records that scope a caller’s file and shell operations to a subset of mounts (the session’s allowlist). Create a session, then pass its id as session_id= on subsequent calls; the server enforces the allowlist and raises SessionForbidden (HTTP 403) for any path outside it.

Async	Sync	Returns	Notes
`create_session(id, *, allowed_mounts=None)`	`create_session_sync(...)`	`SessionInfo`	Creates a session on the server. Raises `VfsError` on a duplicate id or invalid input.
`list_sessions()`	`list_sessions_sync()`	`list[SessionInfo]`	Lists all registered sessions.
`delete_session(id)`	`delete_session_sync(id)`	`None`	Deletes a session by id.

session = await ws.create_session("agent-42", allowed_mounts=["/data"])
entries = await ws.ls("/data", session_id=session.id)
await ws.delete_session(session.id)

SessionInfo fields: id: str, allowed_mounts: list[str].

Strict mount validation (Python)

Call validate() immediately after constructing Workspace so a misconfigured server fails fast instead of silently routing reads to the wrong store.

ws = Workspace(
    {
        "/": r2(bucket="agent-orc-prod", endpoint="https://<acct>.r2.cloudflarestorage.com"),
    },
    base_url=os.getenv("VFS_BASE_URL", "http://localhost:8080"),
    token=os.environ["VFS_TOKEN"],
)
await ws.validate()   # raises MountMismatch or MountUnavailable if something is wrong

Validation raises:

MountMismatch: a declared path is not registered on the server, or the backend kind, bucket, or endpoint does not match what the server reports.
MountUnavailable: the server has the mount but its backend failed to initialize at boot; the server-reported reason is included in the exception message.

await ws.write("/data/report.md", "# Report\n", mime="text/markdown")

entries = await ws.ls("/data")
entry = await ws.stat("/data/report.md")
text = await ws.cat_text("/data/report.md")
raw = await ws.cat("/data/report.md")
matches = await ws.grep("Report", "/data/report.md")
found = await ws.find("/data", name="report.md")

await ws.delete("/data/report.md")

Shell execution

execute and execute_sync post to POST /vfs/exec. There is no host shell fallback; unsupported syntax raises a VfsError subclass.

out = await ws.execute("grep ALERT /s3/log.jsonl | wc -l", cwd="/")

if out.exit_code != 0:
    raise RuntimeError(out.stderr or f"vfs command failed: {out.exit_code}")

print(out.stdout)

Response models

All responses are Pydantic v2 models. Use .model_dump() for plain dicts.

class Output(BaseModel):
    stdout: str = ""
    stderr: str = ""
    exit_code: int = 0
    duration_ms: int = 0
    truncated: bool = False

class Entry(BaseModel):
    name: str
    path: str
    is_dir: bool = False
    size: int | None = None
    mtime: str | None = None
    mime: str | None = None

class GrepMatch(BaseModel):
    path: str
    line: int
    col: int
    snippet: str

class MountInfo(BaseModel):
    name: str
    path_prefix: str
    mode: str
    ttl_seconds: int = 0
    status: str                    # "ready" | "unavailable"
    reason: str = ""               # set when status="unavailable"
    backend: MountBackend           # kind, bucket, endpoint, prefix

class MountBackend(BaseModel):
    kind: str                      # "ram" | "r2"
    bucket: str = ""
    endpoint: str = ""
    prefix: str = ""

MountBackend is not exported from the top-level agent_orc_vfs package; access it as an attribute of a MountInfo instance (mount_info.backend), or import it directly from agent_orc_vfs.workspace. Only MountInfo is part of the package’s public __all__.

`file_prompt`

ws.file_prompt returns a system-prompt fragment describing the configured mounts. Pass it to the agent’s instructions or prepend it to the system prompt.

print(ws.file_prompt)

You have access to a virtual filesystem with the following mounts:
- /data (RAM, ephemeral; lost between sandbox sessions)
- /s3 (R2 bucket "agent-orc-prod"; persistent)

Use shell commands like `cat`, `ls`, `grep`, `find`, `cp`, `head`, `tail`, `wc`
through the Bash tool. The shell supports pipes, redirects, and globs but not
variables, command substitution, or control flow.

Override the rendering by passing file_prompt_template=callable to the constructor.

OpenAI function tools

tools(ws) returns a list of OpenAI chat-completions tool dicts. Each entry carries an extra executor callable used for local dispatch. The surface is intentionally two tools:

Tool	Purpose
`vfs_execute`	Sealed shell entry point. Builtins: `ls`, `cat`, `find`, `grep`, `head`, `tail`, `mkdir`, `rm`, `mv`, `cp`, `wc`, `echo`, `stat`, `pwd`, `cd`, `touch`. Pipes, redirects, globs, and `&&`/`\|\|`/`;` chaining.
`vfs_grep`	Bounded structured search; returns `list[GrepMatch]`.

from agent_orc_vfs import dispatch_tool, tool_schemas, tools

tool_defs = tools(ws)
openai_tools = tool_schemas(tool_defs)

# Send openai_tools to the model:
# response = await openai.chat.completions.create(..., tools=openai_tools)

# Dispatch a tool call returned by the model:
output = await dispatch_tool(
    tool_defs,
    "vfs_execute",
    {"cmd": "grep ALERT /s3/log.jsonl | wc -l"},
)

Helpers exposed alongside tools(...):

Helper	Purpose
`tool_schemas(tool_defs)`	Returns OpenAI-safe schemas with `executor` keys stripped.
`tool_executors(tool_defs)`	Returns a mapping of tool name to async callable.
`dispatch_tool(tool_defs, name, arguments)`	Awaits the executor by name and returns a string result. Catches `VfsError` and serializes structured results as JSON.

Errors

All non-2xx responses are mapped to typed exceptions:

from agent_orc_vfs import (
    VfsError,
    PermissionDenied,
    NotFound,
    MountUnavailable,
    MountMismatch,
    SessionForbidden,
    InvalidPath,
    UnsupportedShellFeature,
    CommandNotFound,
    DriverError,
)

try:
    await ws.cat("/secret/file")
except PermissionDenied as exc:
    print(exc.code, exc.allowed)
except NotFound as exc:
    print(exc.detail.get("path"))
except VfsError as exc:
    print(exc.code, exc.message, exc.detail)

Each exception carries code (string), message, and detail (dict). The shared error code table is in Error codes below.

TypeScript: `@agent-orc/vfs`

An ESM + CJS package that ships a thin Workspace HTTP client, mount factories, a Vercel AI SDK / OpenAI tool bundle, and an in-package SandboxClient facade.

Install

The package is not published to npm. Install it from this repository:

bun add file:../virtualfs/sdk/ts

Build outputs ship to dist/index.js (ESM), dist/index.cjs (CJS), and dist/index.d.ts. The only runtime dependency is zod ^3.23.8.

Workspace

import { Workspace, ram } from "@agent-orc/vfs";

const ws = new Workspace(
  {
    "/": ram(),
  },
  {
    baseUrl: process.env.VFS_BASE_URL ?? "http://localhost:8080",
    token: process.env.VFS_TOKEN ?? "${VFS_AUTH_TOKEN}",
  },
);

Constructor signature:

new Workspace(
  mounts: Record<string, Mount>,
  opts: {
    baseUrl: string;
    token: string;
    filePromptTemplate?: (mounts: Record<string, Mount>) => string;
  },
)

The client uses the global fetch and exposes one request<T>(method, path, body?) private helper that injects Authorization: Bearer ${TOKEN} and parses non-2xx responses through parseErrorResponse.

Mount factories

import { ram, r2 } from "@agent-orc/vfs";

ram();                                                                             // RamMount
r2({ bucket: "agent-orc-prod" });                                                  // R2Mount
r2({ bucket: "agent-orc-prod", prefix: "kb/" });                                   // R2Mount with prefix
r2({ bucket: "agent-orc-prod", endpoint: "https://<acct>.r2.cloudflarestorage.com" }); // explicit endpoint

Mount union: Mount = R2Mount | RamMount | NotionMount. NotionMount is a placeholder for a future driver. describeMountAt(mountPath, mount) is exported for custom prompt templates.

Typed file operations

Method	Returns	Notes
`execute(cmd, opts?: { cwd?, sessionId? })`	`Promise<Output>`	Sealed shell.
`cat(path, opts?: { rangeStart?, rangeEnd?, sessionId? })`	`Promise<Buffer>`	Decodes `text` or `base64` envelope.
`catText(path, opts?)`	`Promise<string>`	UTF-8 convenience wrapper.
`ls(path, opts?: { recursive?, limit?, cursor?, sessionId? })`	`Promise<Entry[]>`
`stat(path, opts?: { sessionId? })`	`Promise<Entry \| null>`	Returns `null` on `NOT_FOUND`. Other errors throw.
`find(path, opts?: { name?, type?: "file" \| "dir", limit?, sessionId? })`	`Promise<Entry[]>`
`grep(path, pattern, opts?: { recursive?, regex?, maxMatches?, sessionId? })`	`Promise<GrepMatch[]>`	Note arg order: `(path, pattern)`.
`write(path, content, opts?: { mime?, sessionId? })`	`Promise<Entry>`	Accepts `string` or `Uint8Array`. Buffers go base64.
`delete(path, opts?: { recursive?, sessionId? })`	`Promise<void>`
`mounts()`	`Promise<MountInfo[]>`	Live mount table from the server.
`validate()`	`Promise<void>`	Asserts declared mount specs match the server’s live table. Rejects with `MountMismatch` or `MountUnavailable` on failure.

Every opts object above also accepts sessionId?: string, sent to the server as session_id, to scope the call to a session’s mount allowlist. See Sessions below.

Sessions

Sessions are server-side records that scope a caller’s file and shell operations to a subset of mounts (the session’s allowlist). Create a session, then pass its id as sessionId in an op’s opts to enforce the allowlist; a path outside it rejects with SessionForbidden.

import { Session } from "@agent-orc/vfs";

const session: Session = await ws.createSession("agent-42", { allowedMounts: ["/data"] });
const entries = await ws.ls("/data", { sessionId: session.id });
await ws.deleteSession(session.id);

Method	Returns	Notes
`createSession(id, opts?: { allowedMounts? })`	`Promise<Session>`	Creates a session on the server.
`listSessions()`	`Promise<Session[]>`	Lists all registered sessions.
`deleteSession(id)`	`Promise<void>`	Deletes a session by id.

Session fields: id: string, allowedMounts: string[].

Strict mount validation (TypeScript)

Call validate() immediately after constructing Workspace so a misconfigured server fails fast instead of silently routing reads to the wrong store.

import { Workspace, r2, MountMismatch, MountUnavailable } from "@agent-orc/vfs";

const ws = new Workspace(
  { "/": r2({ bucket: "agent-orc-prod", endpoint: "https://<acct>.r2.cloudflarestorage.com" }) },
  { baseUrl: process.env.VFS_BASE_URL!, token: process.env.VFS_TOKEN! }
);

await ws.validate(); // throws MountMismatch or MountUnavailable if something is wrong

Validation rejects with:

MountMismatch: a declared path is not registered on the server, or the backend kind, bucket, or endpoint does not match what the server reports.
MountUnavailable: the server has the mount but its backend failed to initialize at boot; the server-reported reason is included.

The TypeScript stat() swallows NOT_FOUND and returns null, while the Python stat() raises NotFound. Pick one shape per call site rather than mixing.

const out = await ws.execute("grep ALERT /s3/log.jsonl | wc -l", { cwd: "/" });
if (out.exitCode !== 0) {
  throw new Error(out.stderr || `vfs command failed: ${out.exitCode}`);
}

await ws.write("/data/report.md", "# Report\n", { mime: "text/markdown" });
const entries = await ws.ls("/data");
const text = await ws.catText("/data/report.md");
const matches = await ws.grep("/data/report.md", "Report");

Response types

interface Output {
  stdout: string;
  stderr: string;
  exitCode: number;
  durationMs: number;
  truncated?: boolean;
}

interface Entry {
  path: string;
  name: string;
  isDir: boolean;
  size?: number;
  mtime?: string;
  mime?: string;
}

interface GrepMatch {
  path: string;
  line: number;
  col: number;
  snippet: string;
}

interface MountBackend {
  kind: string;          // "ram" | "r2"
  bucket?: string;
  endpoint?: string;
  prefix?: string;
}

interface MountInfo {
  name: string;
  pathPrefix: string;
  mode: string;
  ttlSeconds: number;
  status: string;        // "ready" | "unavailable"
  reason?: string;       // set when status="unavailable"
  backend: MountBackend;
}

`file_prompt`

ws.file_prompt is a getter, not a method. It renders the configured mounts using defaultFilePromptTemplate unless opts.filePromptTemplate was supplied.

const systemPrompt = ws.file_prompt;

Agent tools

tools(ws) returns a VfsTools object compatible with the Vercel AI SDK tools: argument and with manual OpenAI function-calling loops. Each entry has a Zod inputSchema and an execute(input) callable that routes through Workspace.

import { tools } from "@agent-orc/vfs";

const vfsTools = tools(ws);

// Vercel AI SDK:
const result = await generateText({ model, tools: vfsTools, ... });

// OpenAI function calling: invoke vfsTools.vfs_execute.execute(...) when
// the model returns a tool_call with the matching name.
const out = await vfsTools.vfs_execute.execute({
  cmd: "grep ALERT /s3/log.jsonl | wc -l",
});

The two-tool surface mirrors the Python adapter: vfs_execute returns { stdout, stderr, exitCode, durationMs }, and vfs_grep returns { matches }.

`SandboxClient`

The TypeScript SDK ships its sandbox facade in-package. There is no separate @agent-orc/openai-vfs for TypeScript; the OpenAI Agents adapter is Python-only.

import { SandboxClient } from "@agent-orc/vfs";

const sandbox = new SandboxClient(ws);
const sessionId = await sandbox.openSandbox();          // UUID, no container provisioned
await sandbox.runCommand("echo ok > /data/out.txt");
const body = await sandbox.readFile("/data/out.txt");   // Buffer
await sandbox.writeFile("/data/out.txt", "new contents");
await sandbox.close();                                  // no-op in v1.5

Method	Returns	Routes to
`openSandbox()`	`Promise<string>`	Generates a fresh UUID on every call; repeated calls return different ids. No HTTP call.
`runCommand(cmd, opts?: { cwd? })`	`Promise<{ stdout, stderr, exitCode }>`	`Workspace.execute(cmd, opts)`
`readFile(path)`	`Promise<Buffer>`	`Workspace.cat(path)`
`writeFile(path, content)`	`Promise<void>`	`Workspace.write(path, content)`
`close()`	`Promise<void>`	Clears the cached session id. No HTTP call.

Unlike the Python agent-orc-vfs-openai adapter’s open_sandbox(), which memoizes and returns the same id on every call, the TypeScript openSandbox() is not memoized.

Errors

The TypeScript SDK has a base VfsError class with code, message, httpStatus, and optional allowed, plus three dedicated subclasses: MountUnavailable (MOUNT_UNAVAILABLE), MountMismatch (MOUNT_MISMATCH), and SessionForbidden (SESSION_FORBIDDEN, HTTP 403). parseErrorResponse maps those three codes to their subclass and falls back to plain VfsError for every other code. Catch a specific subclass, or branch on err.code for the rest.

import { VfsError, SessionForbidden } from "@agent-orc/vfs";

try {
  await ws.cat("/secret/file");
} catch (err) {
  if (err instanceof SessionForbidden) {
    console.warn("session mount allowlist denied this path");
  } else if (err instanceof VfsError) {
    if (err.code === "PERMISSION_DENIED") {
      console.warn("not allowed; permitted prefixes:", err.allowed);
    } else {
      console.error(err.code, err.message, err.httpStatus);
    }
  } else {
    throw err;
  }
}

Claude adapter: `@agent-orc/claude-vfs`

A TypeScript-only adapter that exposes Claude’s Bash tool and routes its invocations through Workspace.execute(). Lives at virtualfs/sdk/adapters/claude-sdk.

Install

bun add file:../virtualfs/sdk/adapters/claude-sdk

The adapter has @anthropic-ai/sdk as an optional peer dependency (>=0.26.0); the adapter itself does not import the SDK at module load time, so it can be used with any Anthropic SDK loop or with no SDK at all.

Surface

bashTool(ws) returns { definition, handler }:

interface BashToolDefinition {
  type: "bash_20250124";
  name: "Bash";
}

interface BashToolInput {
  command: string;
  restart?: boolean;
}

interface BashToolResult {
  output: string;     // stdout, plus stderr appended when non-empty
  exit_code: number;  // surfaced separately so callers can gate on non-zero
}

function bashTool(
  ws: Pick<Workspace, "execute">,
): { definition: BashToolDefinition; handler: (input: BashToolInput) => Promise<BashToolResult> };

Usage

import Anthropic from "@anthropic-ai/sdk";
import { Workspace, ram } from "@agent-orc/vfs";
import { bashTool } from "@agent-orc/claude-vfs";

const ws = new Workspace(
  { "/": ram() },
  { baseUrl: "http://localhost:8080", token: "${VFS_AUTH_TOKEN}" },
);
const bash = bashTool(ws);

const client = new Anthropic();
const message = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 4096,
  tools: [bash.definition],
  messages: [{ role: "user", content: "Count ALERT lines in /data/log.jsonl" }],
});

for (const block of message.content) {
  if (block.type === "tool_use" && block.name === "Bash") {
    const result = await bash.handler(block.input as { command: string });
    // Send result.output back as a tool_result content block.
    // Inspect result.exit_code to decide whether to follow up.
  }
}

Behavior notes

restart: true is a no-op. The VFS shell is stateless, so the handler returns a notice with exit_code: 0 instead of clearing any session state.
An empty command string returns { output: "", exit_code: 0 }.
stdout and stderr are concatenated into output; stderr is appended after stdout when both are present.
Any thrown error (VfsError, network error, etc.) is caught and surfaced as { output: error.message, exit_code: 1 } so the agent loop can keep running.

This adapter is not a sandbox: Claude itself runs locally, only its Bash tool calls are intercepted. For a sandbox-shaped facade, use SandboxClient from @agent-orc/vfs (TypeScript) or agent-orc-vfs-openai (Python).

OpenAI Agents adapter: `agent-orc-vfs-openai`

A Python-only adapter that wraps a Workspace in a sandbox-shaped facade for agent runtime code that expects BaseSandboxClient-style operations. Lives at virtualfs/sdk/adapters/openai-agents.

Install

pip install ./virtualfs/sdk/py
pip install ./virtualfs/sdk/adapters/openai-agents

The adapter intentionally does not import openai-agents at module load time. The OpenAI Agents SDK’s sandbox surface (BaseSandboxClient, SandboxSession) is still beta; this package exposes a smaller SandboxClientProtocol that is direct-protocol compatible today and can be wrapped in the future when agent-orc adopts the official shape.

Surface

from agent_orc_vfs_openai import (
    SandboxClient,
    SandboxClientProtocol,
    CommandResult,
)

Symbol	Description
`SandboxClient(workspace)`	Routes each method through the supplied `agent_orc_vfs.Workspace`. Async-only API.
`SandboxClientProtocol`	`typing.Protocol` (`@runtime_checkable`) that `SandboxClient` implements; lets callers type-check without importing `openai-agents`.
`CommandResult`	Dataclass returned by `run_command`. Fields: `stdout`, `stderr`, `exit_code`, `duration_ms`. Property `ok` is `True` when `exit_code == 0`.

Methods

Method	Behavior
`await open_sandbox() -> str`	Returns a UUID4 string stable for this client instance. No container is provisioned; subsequent calls return the same id.
`await run_command(cmd, cwd=None) -> CommandResult`	Awaits `Workspace.execute(cmd, cwd=cwd)` and adapts the result.
`await read_file(path) -> bytes`	Awaits `Workspace.cat(path)`. Binary-safe.
`await write_file(path, content: bytes) -> None`	Awaits `Workspace.write(path, content)`. Bytes are sent base64-encoded.
`await close() -> None`	No-op. The `Workspace` HTTP client lifecycle is the caller’s responsibility (call `await ws.aclose()` separately).

Usage

import os

from agent_orc_vfs import Workspace, r2
from agent_orc_vfs_openai import SandboxClient


async def run() -> None:
    ws = Workspace(
        {
            "/": r2(bucket="agent-orc-prod"),
        },
        base_url=os.environ["VFS_BASE_URL"],
        token=os.environ["VFS_TOKEN"],
    )

    sandbox = SandboxClient(ws)
    session_id = await sandbox.open_sandbox()
    result = await sandbox.run_command("grep alert /s3/log.jsonl | wc -l")

    if not result.ok:
        raise RuntimeError(result.stderr or f"exit {result.exit_code}")

    print(session_id, result.stdout)
    await sandbox.close()
    await ws.aclose()

VfsError and its subclasses propagate from run_command, read_file, and write_file exactly as they do from the underlying Workspace.

Error codes

Every endpoint uses the shared { "error": { "code", "message", ... } } envelope. The Python SDK maps each code to a dedicated exception class. The TypeScript SDK also has dedicated subclasses for three codes (MountUnavailable, MountMismatch, SessionForbidden, all extending VfsError); every other code surfaces only as a plain VfsError with code set, so callers branch on err.code for those.

Code	Python class	When
`PERMISSION_DENIED`	`PermissionDenied`	Path is outside an allowed prefix. `detail.allowed` lists permitted prefixes.
`NOT_FOUND`	`NotFound`	Path or mount entry does not exist. `detail.path` carries the requested path.
`MOUNT_UNAVAILABLE`	`MountUnavailable`	The server has no driver registered for the mount, or the driver failed to initialize.
`INVALID_PATH`	`InvalidPath`	Path is malformed or fails normalization.
`UNSUPPORTED_SHELL_FEATURE`	`UnsupportedShellFeature`	Parsed command uses variable expansion, command substitution, control flow, subshells, or backgrounding.
`COMMAND_NOT_FOUND`	`CommandNotFound`	Command is not in the sealed builtin registry; no host `PATH` lookup is performed.
`DRIVER_ERROR`	`DriverError`	Underlying mount driver returned an error.
`SESSION_FORBIDDEN`	`SessionForbidden`	A `session_id` was supplied and the resolved path falls outside that session’s `allowed_mounts` (HTTP 403); `detail` carries `session` and `path`. TS exposes a matching `SessionForbidden` subclass of `VfsError`.
`HTTP_ERROR` (Python) / fallback `code` (TS)	`VfsError`	Any other failure, including non-JSON error bodies.

The cmd shape that triggers UNSUPPORTED_SHELL_FEATURE and the full builtin list live in the Shell Parser and Compiler section of the API reference.

Examples

Runnable scripts ship with the SDKs:

Path	What it shows
`virtualfs/examples/python/01_basic_execute.py`	`await ws.execute("grep alert /s3/log.jsonl \| wc -l")` end to end.
`virtualfs/examples/python/02_read_write.py`	Typed file helpers: `write`, `cat`, `ls`, `find`, `delete`.
`virtualfs/examples/python/03_with_openai_tools.py`	`tools(ws)`, `tool_schemas(...)`, `dispatch_tool(...)` against the OpenAI SDK.
`virtualfs/examples/python/04_with_openai_agents.py`	`SandboxClient(ws)` driven through an agent loop.
`virtualfs/examples/python/06_filesystem_walk.py`	Treating all mounts as one unified tree: `find`/`grep`/`ls -R` from the root path.
`virtualfs/examples/typescript/01-basic-execute.ts`	`Workspace.execute()`.
`virtualfs/examples/typescript/02-read-write.ts`	Typed helpers and `mounts()`.
`virtualfs/examples/typescript/03-agent-tools.ts`	`tools(ws)` as a Vercel AI SDK tool bundle.
`virtualfs/examples/typescript/04-claude-bash-tool.ts`	`bashTool(ws)` dry-run loop without an Anthropic API key.
`virtualfs/examples/typescript/05-sandbox-client.ts`	`SandboxClient(ws)`.
`virtualfs/examples/typescript/06-filesystem-walk.ts`	Treating all mounts as one unified tree: `find`/`grep`/`ls -R` from the root path.

To run them, boot a server with go run ./virtualfs/cmd/vfs serve, export VFS_BASE_URL and VFS_TOKEN, then follow the README.md in the example directory.

​Package map

​Server prerequisites

​Python: agent-orc-vfs

​Install

​Workspace

​Mount factories

​Typed file operations

​Sessions

​Strict mount validation (Python)

​Shell execution

​Response models

​file_prompt

​OpenAI function tools

​Errors

​TypeScript: @agent-orc/vfs

​Install

​Workspace

​Mount factories

​Typed file operations

​Sessions

​Strict mount validation (TypeScript)

​Response types

​file_prompt

​Agent tools

​SandboxClient

​Errors

​Claude adapter: @agent-orc/claude-vfs

​Install

​Surface

​Usage

​Behavior notes

​OpenAI Agents adapter: agent-orc-vfs-openai

​Install

​Surface

​Methods

​Usage

​Error codes

​Examples

Package map

Server prerequisites

Python: `agent-orc-vfs`

Install

Workspace

Mount factories

Typed file operations

Sessions

Strict mount validation (Python)

Shell execution

Response models

`file_prompt`

OpenAI function tools

Errors

TypeScript: `@agent-orc/vfs`

Install

Workspace

Mount factories

Typed file operations

Sessions

Strict mount validation (TypeScript)

Response types

`file_prompt`

Agent tools

`SandboxClient`

Errors

Claude adapter: `@agent-orc/claude-vfs`

Install

Surface

Usage

Behavior notes

OpenAI Agents adapter: `agent-orc-vfs-openai`

Install

Surface

Methods

Usage

Error codes

Examples