Skip to main content
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

​
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.