VirtualFS

Tenant-scoped, sealed virtual filesystem shared by agents, the conductor, the dashboard, and platform services.

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 VirtualFS service uses :8090.
• Authentication: VFS_AUTH_TOKEN selects bearer auth. Without it, smokeAuth accepts the dev-token printed in the boot banner.
• 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.