> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orcapods.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

<CardGroup cols={2}>
  <Card title="SDKs" icon="code" href="/virtualfs/sdks">
    Python, TypeScript, the Claude Bash adapter, and the OpenAI Agents sandbox adapter.
  </Card>

  <Card title="API Reference" icon="server" href="/virtualfs/api">
    Authentication, agent tool bundle, typed endpoints, sealed shell, deployment.
  </Card>
</CardGroup>

***

## 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](/virtualfs/api#agent-tool-bundle).                       |
| Calling VirtualFS from Python code                         | `agent-orc-vfs` (`Workspace`, mount factories, OpenAI tools). See [Python SDK](/virtualfs/sdks#python-agent-orc-vfs).                      |
| Calling VirtualFS from TypeScript code                     | `@agent-orc/vfs` (`Workspace`, Vercel AI / OpenAI tools, `SandboxClient`). See [TypeScript SDK](/virtualfs/sdks#typescript-agent-orc-vfs). |
| Routing Claude's Bash tool through VirtualFS               | `@agent-orc/claude-vfs`. See [Claude adapter](/virtualfs/sdks#claude-adapter-agent-orc-claude-vfs).                                        |
| Wrapping a `Workspace` as a sandbox for OpenAI Agents code | `agent-orc-vfs-openai`. See [OpenAI Agents adapter](/virtualfs/sdks#openai-agents-adapter-agent-orc-vfs-openai).                           |
| Calling the HTTP API directly from another language        | The typed JSON endpoints. See [Typed File Operations](/virtualfs/api#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](/concepts/storage).