Storage and Files

Storage Model

Orca has two storage surfaces:

VirtualFS-backed filesystem tools (read_file, write_file, list_dir, delete_file) expose scoped paths under conventional directories such as /agents, /pools, /s3, /data, and /kb.
Artifact tools (save_artifact, get_artifact, list_artifacts) expose raw run/session-keyed S3-compatible objects.
Memory Bank persists per-profile long-lived memories under memory/<profile>/<id>.json when S3-compatible storage is configured. See Memory Bank.

Local Docker uses SeaweedFS. Production can use any S3-compatible backend, including AWS S3, R2, or MinIO.

Environment Contract

VirtualFS is configured from explicit VFS_* variables, or from production defaults when VFS_BACKEND=production is set:

Variable	Description
`VFS_POSTGRES_DSN`	Optional Postgres index cache; falls back to in-memory
`VFS_REDIS_URL`	Optional Redis byte cache; falls back to disabled
`VFS_S3_BUCKET`	S3/R2 bucket for root mount contents (prod profile). When unset, the root mount comes up `unavailable`; use `--profile dev` for an all-RAM local setup.
`VFS_S3_ENDPOINT`	Optional S3-compatible endpoint
`VFS_BACKEND=production`	Also consults generic Postgres, Redis, S3, and R2 environment variables

Mount strictness

A mount is strictly identified by its path AND its backing data source (kind + bucket + endpoint + prefix). The prod, dev, and disk profiles each register one system mount named root at /; /agents, /pools, /s3, /data, and /kb are directories inside that mount, not separate boot-time mounts. Runtime user mounts can still register non-root prefixes, and the dispatcher resolves paths with longest-prefix-wins. Two important consequences:

The server never substitutes a different backend for a missing one. If the prod profile is configured for R2 and R2 is unreachable at boot, the root mount comes up unavailable — not silently backed by RAM.
The client never assumes a mount is what it declares; it checks. Use Workspace.validate() to fail fast on bucket drift or kind mismatch.

Mounts that fail to initialize at boot do not crash the server. The server boots; their entries surface in GET /vfs/mounts with status: "unavailable" and a human-readable reason. Operations on those mounts return MOUNT_UNAVAILABLE.

Single coherent filesystem

The VFS presents path operations as one tree:

Addressable: every byte lives at exactly one absolute path (/agents/..., /data/..., /kb/...), regardless of whether the selected mount is RAM, R2, or another backend.
Navigable: ls / returns top-level directories visible from the active mount table; cd / works; stat / reports a directory.
Searchable: find / and grep -r / traverse the visible tree and apply the active session allowlist before returning entries or matches.
Mutable across subtrees or mounts: cp /agents/x /data/y and mv /a/x /b/y stream bytes through the dispatcher.

Strict identity (above) and unification (here) are independent guarantees. Strict means each mount honestly reports its data source; unification means callers don’t have to enumerate mounts to walk the tree. Together they let an agent treat the substrate like a real filesystem without hiding what’s actually under each subtree. With no VFS_* environment, the runner still boots with an in-memory VirtualFS dispatcher. That keeps @fs, @pool, and @vfs usable for a single runner process, but state is not shared with a separate vfs serve process. Configure both processes with the same VirtualFS backend settings when dashboard Files, vfs serve, and agent tools should see the same data. The dashboard Files page is a VFS client too. From any writable directory, operators can upload files or folders with the Upload menu or by dragging them into the listing. Folder picks and dropped directories preserve relative paths, while the upload queue shows per-file progress, retry, cancel-all, and clear controls. Raw artifacts and Memory Bank persistence are configured from the standard AWS SDK environment plus Orca-specific bucket flags:

Variable	Description
`S3_BUCKET`	Required bucket name
`AWS_REGION`	Region; defaults to `us-east-1`
`AWS_ENDPOINT_URL_S3`	S3-compatible endpoint for SeaweedFS, MinIO, or R2
`AWS_ACCESS_KEY_ID`	Access key
`AWS_SECRET_ACCESS_KEY`	Secret key
`S3_FORCE_PATH_STYLE`	Set `true` for SeaweedFS and MinIO
`S3_CAPACITY_BYTES`	Optional dashboard capacity denominator

Run-event blobs can use a separate internal bucket. This keeps operational run transcripts out of the tenant-facing artifact bucket used by artifact tools, Memory Bank, and the dashboard storage API:

Variable	Description
`INTERNAL_S3_BUCKET`	Optional bucket for `runs/<runId>/events.jsonl` and `runs/<runId>/finished`
`INTERNAL_AWS_REGION`	Region; defaults to `us-east-1`
`INTERNAL_AWS_ENDPOINT_URL_S3`	S3-compatible endpoint
`INTERNAL_AWS_ACCESS_KEY_ID`	Access key
`INTERNAL_AWS_SECRET_ACCESS_KEY`	Secret key
`INTERNAL_S3_FORCE_PATH_STYLE`	Set `true` for SeaweedFS and MinIO

When raw artifact storage is not configured, artifact calls return a “not configured” tool error and the dashboard storage API reports configured: false. When S3_BUCKET is configured for the conductor, startup probes the bucket with a small list request before wiring artifact storage. Missing buckets, wrong endpoints, or invalid credentials fail startup with artifacts.bucket_unavailable instead of silently dropping run-event writes. When INTERNAL_S3_BUCKET is configured, the conductor probes that bucket too and uses it for run-event blobs. If the internal bucket is omitted, run events fall back to the primary S3_BUCKET, so single-bucket local and CI setups need no extra configuration.

Filesystem View

Filesystem tools use absolute POSIX paths and dispatch through VirtualFS. With the default S3/R2-backed root mount, user-facing paths stay stable, while the dispatcher scopes bucket keys under the authenticated tenant’s jail prefix (tenants/{tenant}/...). Entries returned by ls, find, grep, stat, and writes are decoded back to tenant-facing POSIX paths before callers see them.

Path	Auth tenant	Bucket key
`/agents/general/notes.md`	`acme`	`tenants/acme/agents/general/notes.md`
`/pools/research/board/public/posts/x.md`	`acme`	`tenants/acme/pools/research/board/public/posts/x.md`

Every profile has implicit read/write/delete access to /agents/{self}/**.

{
  "fs": {
    "read": ["/datasets/**"],
    "write": ["/shared/{self}/**"],
    "deny": ["/datasets/private/**"]
  }
}

delete defaults to write when omitted. deny overrides all grants.

File Tools

@fs is part of @default.

Tool	Description
`read_file`	Reads text or base64 content from an allowed path
`write_file`	Writes text or base64 content to an allowed path
`list_dir`	Lists immediate children visible to the session policy
`delete_file`	Deletes an allowed file

Relative paths are resolved under the agent home. For example, write_file("notes.md") writes /agents/{self}/notes.md. When a VirtualFS dispatcher is wired, @fs, @pool, @sandbox-transfer, and @vfs share the same backing substrate. A file written with write_file under /agents/{self} is visible to VirtualFS shell commands such as vfs_execute running inside a sandbox.

Artifact Tools

@artifacts is opt-in. These tools use run/session-keyed object paths:

runs/<runId>/sessions/<sessionId>/<path>

When there is no run ID, objects are written under shared/sessions/<sessionId>/....

Tool	Description
`save_artifact`	Saves text or base64 content under the current run/session
`get_artifact`	Reads by relative `path` or absolute `key`
`list_artifacts`	Lists by prefix; defaults to the current run prefix

Inline tool payloads are capped at 8 MiB.

Dashboard Storage API

The conductor exposes storage endpoints used by the dashboard’s storage browser:

Method	Path	Description
`GET`	`/api/storage/info`	Bucket usage and top-level prefix breakdown
`GET`	`/api/storage/objects?prefix=...`	List objects by key prefix
`GET`	`/api/storage/objects/{key}`	Preview object content inline; `key` may contain multiple path segments
`PUT`	`/api/storage/objects/{key}`	Upload an object (raw body, capped at 8 MiB); `key` may contain multiple path segments
`DELETE`	`/api/storage/objects/{key}`	Delete one object — or every object under a prefix when the multi-segment key ends with `/`

Non-UTF-8 object content is base64 encoded in GET responses. DELETE against a folder prefix walks up to 1000 entries (one List page) and removes them serially.

Local SeaweedFS

The compose stack starts SeaweedFS and creates the default bucket:

make storage-up
make storage-smoke

The default local endpoint is http://localhost:8333, bucket agent-artifacts, access key agent-orc, and secret agent-orc-secret.

Get Started

Core Concepts

Guides

Storage and Files

Storage Model

Environment Contract

Mount strictness

Single coherent filesystem

Filesystem View

File Tools

Artifact Tools

Dashboard Storage API

Local SeaweedFS

​Storage Model

​Environment Contract

​Mount strictness

​Single coherent filesystem

​Filesystem View

​File Tools

​Artifact Tools

​Dashboard Storage API

​Local SeaweedFS

Storage Model

Environment Contract

Mount strictness

Single coherent filesystem

Filesystem View

File Tools

Artifact Tools

Dashboard Storage API

Local SeaweedFS