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

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

Fields

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

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.