Skip to main content
WandbVFS mounts Weights & Biases (W&B) experiments as read-only files: each run’s metadata, config, summary, metric history and logged files. Set up the API key and entities as in Weights & Biases setup.

Install

Configure

page_size and max_pages bound each listing, and base_url points at another W&B server.

Fields

number
default:"DEFAULT_TIMEOUT"
Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.
string[]
required
W&B entities (users or teams) the mount shows as top-level directories; no other entity is reachable.
string
default:"''"
secret
W&B API key, sent as HTTP Basic auth. Empty sends no credentials.
string
default:"'https://api.wandb.ai'"
W&B API root. Queries go to its /graphql, and only downloads from the same origin carry the key.
number
default:"100"
Items per GraphQL page, and steps per window when reading history.jsonl.
number
default:"10000"
The most pages one listing or history read fetches. Past it the read fails rather than return a partial result.
Fields marked secret are redacted in snapshots.

Authentication

The API key is sent as HTTP Basic auth and reads what its user can read. Mirage does not discover entities from the key: set entities to the user or team segment of a project URL (wandb.ai/<entity>/<project>). An empty api_key sends no credentials. Only downloads from the base_url origin carry the key.

Layout

A path is /<entity>/<project>/<run-id>/. Run IDs name the folders, so runs that share a display name stay separate. files/ holds the run’s files at their relative paths, as raw bytes. run.json holds the run’s metadata:

Behavior

  • Read only: the mount registers no write operations and no W&B CLI.
  • run.json: unavailable metadata is null; empty tags, zero counts, false permissions and original timestamp strings are kept. user is the run’s creator, not the key’s user, and is null when the creator is missing. Machine and runtime details are in files/wandb-metadata.json when uploaded. Listing and stat fetch none of these fields.
  • config.json and summary.json: config.json unwraps W&B’s value envelopes. summary.json is the stored summary, which can differ from the best value in history. Both keep run-defined keys, nested values, nulls and metric names holding / or ..
  • history.jsonl: the full, unsampled history, in order, with missing keys, nulls and logged training-step fields kept; _step and a training-step metric are separate values. The last step is fixed when a read begins, so rows logged later show on the next read. Reads stream, so head stops before the whole history is fetched.
  • Sizes: run.json, config.json, summary.json and history.jsonl have unknown sizes; file sizes come from W&B’s file metadata.
  • Pagination: listings follow W&B pagination, page_size (100, at most 1000) items per page and at most max_pages (10000) pages. Running out fails rather than return a partial list. Recursive du stops at 1000 entries.

Browser

@struktoai/mirage-browser ships the same VFS, built the same way with its buildVfs. It calls W&B with the browser’s fetch, so it works only where the service’s CORS rules allow the page’s origin, and the API key reaches the page.

VFS.md

The VFS.md an agent reads with Weights & Biases mounted at /<path>.
Virtual FilesystemVFS Layout/<path>
  • Read only; only configured entities are visible. Run ids are stable, display names may repeat.
  • run.json holds identity, creator, sweep, group, tags, timestamps, notes and system metrics; its read_only is W&B’s permission, not the mount mode.
  • history.jsonl is the full unsampled history in logged order and can be large; head streams a prefix.
  • summary.json holds stored values, not history maxima.
  • files/ keeps run-relative paths; files/wandb-metadata.json describes the machine and environment.
Supported Unix Commands for VFSUnix commands work on each path as on a local filesystem, as far as the path supports them:Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:Run man <cmd> or <cmd> --help for one command’s usage.