Skip to main content
LangfuseVFS mounts one Langfuse project as read-only files: its traces with their observations and scores, sessions, prompt versions and datasets. Set up the key pair as in Langfuse setup.

Install

Configure

defaultTraceLimit sets how many traces a listing shows, and defaultFromTimestamp lists only traces from an ISO 8601 time on.

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
Langfuse project public key.
string
required
secret
Langfuse project secret key.
string
default:"'https://cloud.langfuse.com'"
Langfuse API host; override for a self-hosted or regional instance.
number
default:"100"
The most traces one trace listing (traces/ or a session’s traces) shows. An older trace is still readable by its id.
string
List only traces from this ISO 8601 timestamp on. Unset lists whatever the project holds, up to defaultTraceLimit.
Fields marked secret are redacted in snapshots.

Authentication

The mount reads with a project’s key pair, the public key (pk-lf-...) and the secret key (sk-lf-...), and sees only that project. host is the project’s region, such as https://cloud.langfuse.com (EU) or https://us.cloud.langfuse.com (US), or a self-hosted URL. The mount reads the Langfuse v4 API, so a self-hosted instance must run Langfuse v4.

Layout

  • traces/: one .json file per trace: the trace’s root observation, with its other observations (spans, generations, events) in observations and its scores in scores. input and output are the strings Langfuse stores; jq '.input | fromjson' parses a JSON one.
  • sessions/: the sessions of the traces traces/ lists, each holding its own traces.
  • prompts/: one folder per prompt name, one file per version (1.json, 2.json) with the prompt content and metadata.
  • datasets/: one folder per dataset, with items.jsonl (its items) and runs/, one .jsonl file per experiment run.

Behavior

  • Read only: no command changes Langfuse.
  • Trace limit: traces/ lists up to defaultTraceLimit traces (100), from defaultFromTimestamp on. The cap bounds the listing, not the tree: stat and cat still reach an older trace by its id, and sessions/<id>/ serves only that session’s traces.
  • Search: grep and rg read each file as cat renders it. Langfuse has no content search, so grep -r over traces/ reads every trace the listing returns.
  • No counts: Langfuse has no count endpoint, so wc -l traces/ is not supported.

Browser

The browser LangfuseVFS from @struktoai/mirage-browser takes the same fields.
  • The secret key reaches the page, so anyone who loads it can read the project.

VFS.md

The VFS.md an agent reads with Langfuse mounted at /<path>.
Virtual FilesystemVFS Layout/<path>
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.