VirtualFS - Orca

VirtualFS is the Orca shared filesystem. It exposes mounted backends (RAM, Cloudflare R2, S3) over a single HTTP surface with tenant-scoped ACLs, a sealed shell subset for agents, typed file ops for application code, and matching cache layers for index and byte storage. Agents perceive it as a normal filesystem reached through the vfs_execute and vfs_grep tool bundle. Application code reaches the same paths through the typed /vfs/... JSON endpoints or one of the language SDKs.

SDKs

Python, TypeScript, the Claude Bash adapter, and the OpenAI Agents sandbox adapter.

API Reference

Authentication, agent tool bundle, typed endpoints, sealed shell, deployment.

When to use which surface

You are…	Use
Building an agent profile in the runner	The `@vfs` capability bundle (`vfs_execute`, `vfs_grep`). See Agent Tool Bundle.
Calling VirtualFS from Python code	`agent-orc-vfs` (`Workspace`, mount factories, OpenAI tools). See Python SDK.
Calling VirtualFS from TypeScript code	`@agent-orc/vfs` (`Workspace`, Vercel AI / OpenAI tools, `SandboxClient`). See TypeScript SDK.
Routing Claude’s Bash tool through VirtualFS	`@agent-orc/claude-vfs`. See Claude adapter.
Wrapping a `Workspace` as a sandbox for OpenAI Agents code	`agent-orc-vfs-openai`. See OpenAI Agents adapter.
Calling the HTTP API directly from another language	The typed JSON endpoints. See Typed File Operations.

At a glance

Standalone server: go run ./virtualfs/cmd/vfs serve listens on :8080 by default. The compose-backed vfs service listens on :8080 internally and is published on the host as 18080:8080.
Authentication: VFS_AUTH_TOKEN selects bearer auth. Without it, local smokeAuth accepts a caller-supplied bearer token.
Proxies: the conductor mounts VirtualFS at /api/vfs/* and the Vercel dashboard rewrites /vfs/* to a Railway VirtualFS service. Both strip client Authorization headers and inject the server-side token.
Storage backends: RAM (dev profile) or Cloudflare R2/AWS S3 (prod profile); Postgres for the index cache, Redis for the byte cache. The prod, dev, and disk profiles each expose one root mount at /; well-known paths such as /agents, /data, and /kb are directories inside it. Each mount is strictly identified by its backend: there is no silent RAM fallback. If a backend fails to initialize at boot, the affected mount surfaces as unavailable in GET /vfs/mounts while the server continues serving other mounts.

For the underlying concept of catalog hashes, mount drivers, and tenant scoping, see Storage.

SDKs

API Reference

​When to use which surface

​At a glance

When to use which surface

At a glance