Langfuse

The Langfuse VFS exposes LLM observability data (traces, observations, prompts, datasets, scores) as a virtual filesystem mounted at some prefix such as /langfuse/. For credential setup, see Langfuse Setup. Install the extra:

pip install "mirage-ai[langfuse]"

Config

import os

from mirage import MountMode, Workspace
from mirage.vfs.langfuse import LangfuseConfig, LangfuseVFS

config = LangfuseConfig(
    public_key=os.environ["LANGFUSE_PUBLIC_KEY"],
    secret_key=os.environ["LANGFUSE_SECRET_KEY"],
    host=os.environ.get("LANGFUSE_HOST", "https://cloud.langfuse.com"),
)
vfs = LangfuseVFS(config=config)
ws = Workspace({"/langfuse": vfs}, mode=MountMode.READ)

Field	Description
`timeout` 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.
`public_key` required	Langfuse project public key.
`secret_key` required, secret	Langfuse project secret key.
`host` default `'https://cloud.langfuse.com'`	Langfuse API host; override for a self-hosted or regional instance.
`default_trace_limit` default `100`	The most traces one trace listing (`traces/` or a session’s traces) shows. An older trace is still readable by its id.
`default_from_timestamp`	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.

VFS.md

The VFS.md an agent reads with Langfuse mounted at /<path>.

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`langfuse`, read

`/<path>` layout

/<path>
  traces/
    <trace-id>.json
  sessions/
    <session-id>/
      <trace-id>.json
  prompts/
    <prompt-name>/
      <version>.json
  datasets/
    <dataset-name>/
      items.jsonl
      runs/
        <run-name>.jsonl

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.

---
name: workspace-filesystem
description: The virtual filesystem layout of this workspace.
---

# Virtual Filesystem

| Path | Description |
| --- | --- |
| `/<path>` | `langfuse`, read |

## `/<path>` layout

```text
/<path>
  traces/
    <trace-id>.json
  sessions/
    <session-id>/
      <trace-id>.json
  prompts/
    <prompt-name>/
      <version>.json
  datasets/
    <dataset-name>/
      items.jsonl
      runs/
        <run-name>.jsonl
```

## 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.

/langfuse/
  traces/
    <trace-id>.json
    ...
  sessions/
    <session-id>/
      <trace-id>.json
      ...
  prompts/
    <prompt-name>/
      <version>.json
      ...
  datasets/
    <dataset-name>/
      items.jsonl
      runs/
        <run-name>.jsonl
        ...

Example:

/langfuse/
  traces/
    abc123.json
    def456.json
  sessions/
    chat-session-1/
      abc123.json
      ghi789.json
  prompts/
    summarize/
      1.json
      2.json
    classify/
      1.json
  datasets/
    eval-v1/
      items.jsonl
      runs/
        run-2026-04-01.jsonl

Traces

/langfuse/traces/ lists traces (capped at default_trace_limit, 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. Each trace is a .json file: 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

/langfuse/sessions/ lists the sessions of the traces traces/ lists. Each session directory contains trace .json files belonging to that session.

Prompts

/langfuse/prompts/ lists prompt names as directories. Each prompt directory contains version files (1.json, 2.json, etc.) with the prompt content and metadata.

Datasets

/langfuse/datasets/ lists dataset names as directories. Each contains items.jsonl (dataset items) and runs/, one .jsonl file per experiment run on the dataset.

grep and rg

grep and rg read each file as cat renders it, at every scope; grep -r and rg walk a directory. No provider-side content search is used, so a search over traces/ reads every trace the listing returns.

grep -r "error" "/langfuse/traces/"
rg -l "classify" "/langfuse/prompts/"

Limits

Command	Limit behavior
`ls traces/`	Returns up to `default_trace_limit` traces
`cat traces/<id>.json`	Full trace (single doc, no limit needed)
`grep -r traces/`	Reads every trace `ls traces/` lists
`wc -l traces/`	Not supported (Langfuse has no count endpoint)

Cache

The Langfuse VFS uses IndexCacheStore (same as other mounts). Index entries store trace IDs, session IDs, and prompt names.

Example

import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.vfs.langfuse import LangfuseConfig, LangfuseVFS

load_dotenv(".env.development")

config = LangfuseConfig(
    public_key=os.environ["LANGFUSE_PUBLIC_KEY"],
    secret_key=os.environ["LANGFUSE_SECRET_KEY"],
)
vfs = LangfuseVFS(config=config)


async def main():
    ws = Workspace({"/langfuse": vfs}, mode=MountMode.READ)

    # List top-level resources
    r = await ws.shell("ls /langfuse/")
    print(await r.stdout_str())

    # List traces
    r = await ws.shell("ls /langfuse/traces/")
    print(await r.stdout_str())

    # Read a specific trace
    traces = (await r.stdout_str()).strip().splitlines()
    if traces:
        r = await ws.shell(f'cat "/langfuse/traces/{traces[0]}"')
        print((await r.stdout_str())[:500])

    # List prompts
    r = await ws.shell("ls /langfuse/prompts/")
    print(await r.stdout_str())

    # Search the listed traces
    r = await ws.shell('grep -r "error" "/langfuse/traces/"')
    print(await r.stdout_str())

    # List datasets
    r = await ws.shell("ls /langfuse/datasets/")
    print(await r.stdout_str())



if __name__ == "__main__":
    asyncio.run(main())

Shell Commands

Command	Notes
`ls`	List traces, sessions, prompts, datasets
`cat`	Read trace JSON, prompt version, dataset items
`head` / `tail`	Read the beginning/end of a file; directories are rejected
`grep` / `rg`	Lexically search files; recursive forms walk listed files
`jq`	Query JSON trace/prompt data
`stat`	Metadata (trace count, prompt versions, dataset items)
`find`	Search across resources with `-name`
`tree`	Directory tree view

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Traces

Sessions

Prompts

Datasets

grep and rg

Limits

Cache

Example

Shell Commands

​Config

​VFS.md

​Virtual Filesystem

​/<path> layout

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Traces

​Sessions

​Prompts

​Datasets

​grep and rg

​Limits

​Cache

​Example

​Shell Commands

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Traces

Sessions

Prompts

Datasets

grep and rg

Limits

Cache

Example

Shell Commands