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

# Weights & Biases

> Virtualize Weights & Biases runs from Node or the browser.

`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](https://docs.mirage.strukto.ai/home/setup/wandb.md).

## Install

```bash theme={null}
npm install @struktoai/mirage-node
```

## Configure

```ts theme={null}
import { MountMode, Workspace, buildVfs } from '@struktoai/mirage-node'

const wandb = await buildVfs('wandb', {
  entities: ['my-team'],
  api_key: process.env.WANDB_API_KEY,
})
const ws = new Workspace({ '/wandb': wandb }, { mode: MountMode.READ })

const result = await ws.shell('find /wandb/my-team -maxdepth 3 -name run.json')
console.log(result.stdoutText)
await ws.close()
```

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

### Fields

**timeout** `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.

**entities** `string[]` *required*

W\&B entities (users or teams) the mount shows as top-level directories; no other entity is reachable.

**apiKey** `string` (default: '')

W\&B API key, sent as HTTP Basic auth. Empty sends no credentials.

**baseUrl** `string` (default: '[https://api.wandb.ai](https://api.wandb.ai)')

W\&B API root. Queries go to its `/graphql`, and only downloads from the same origin carry the key.

**pageSize** `number` (default: 100)

Items per GraphQL page, and steps per window when reading `history.jsonl`.

**maxPages** `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

```text theme={null}
/wandb/
  my-team/
    image-cls/
      3k9x2m7q/
        run.json
        config.json
        summary.json
        history.jsonl
        files/
          output.log
          wandb-metadata.json
```

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:

| Fields | Contents |
| - | - |
| `entity`, `project`, `run`, `path` | Run identity and its `entity/project/run-id` path |
| `storage_id`, `display_name`, `state` | W\&B's opaque storage ID, display name, and reported state |
| `tags`, `sweep_name`, `group`, `job_type` | Experiment organization |
| `commit`, `created_at`, `heartbeat_at` | Source revision, creation time, and last heartbeat |
| `description`, `notes`, `user` | Run description, notes, and creator's `id`/`name`/`username`/`email` |
| `read_only` | W\&B's reported edit permission; the Mirage mount remains read-only |
| `system_metrics` | Latest system metrics decoded as JSON, retaining nested values |
| `history_line_count`, `history_keys`, `file_count` | History row count, metric-key metadata including the last step, and file count |

## 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](https://docs.mirage.strukto.ai/home/setup/vfs-md.md) an agent reads with Weights & Biases mounted at `/<path>`.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `wandb`, read |
>
> **VFS Layout**
>
> **`/<path>`**
>
> ```text theme={null}
> /<path>
>   <entity>/
>     <project>/
>       <run-id>/
>         run.json
>         config.json
>         summary.json
>         history.jsonl
>         files/
> ```
>
> * 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 VFS**
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | - | - |
> | `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). |
>
> **Limitations of Unix Commands for VFS**
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | - | - |
> | `/<path>` | Read only: no command changes files. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.

> [tab] Raw
>
> ````markdown theme={null}
> ---
> name: workspace-filesystem
> description: The virtual filesystem layout of this workspace.
> ---
>
> # Virtual Filesystem
>
> | Path | Description |
> | --- | --- |
> | `/<path>` | `wandb`, read |
>
> ## VFS Layout
>
> ### `/<path>`
>
> ```text
> /<path>
>   <entity>/
>     <project>/
>       <run-id>/
>         run.json
>         config.json
>         summary.json
>         history.jsonl
>         files/
> ```
>
> - 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 VFS
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | --- | --- |
> | `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). |
>
> ## Limitations of Unix Commands for VFS
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | --- | --- |
> | `/<path>` | Read only: no command changes files. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.
> ````


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.