Langfuse

LangfuseVFS exposes Langfuse projects and traces as a read-only tree. Setup steps for the public/secret keys live at Langfuse Credentials.

Node

pnpm add @struktoai/mirage-node

import { LangfuseVFS, MountMode, Workspace } from '@struktoai/mirage-node'

const lf = new LangfuseVFS({
  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
  secretKey: process.env.LANGFUSE_SECRET_KEY!,
  host: process.env.LANGFUSE_HOST,
})

const ws = new Workspace({ '/lf': lf }, { mode: MountMode.READ })
await ws.shell('ls /lf/traces/')

Browser

pnpm add @struktoai/mirage-browser

import { LangfuseVFS, MountMode, Workspace } from '@struktoai/mirage-browser'

const lf = new LangfuseVFS({
  publicKey: LANGFUSE_PUBLIC_KEY,
  secretKey: LANGFUSE_SECRET_KEY,
})

Config

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

Mount mode

read. For the layout and search behavior see the Python Langfuse docs.

VFS.md

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

Rendered
Raw

Virtual Filesystem

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

VFS Layout

`/<path>`

/<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 |

## VFS Layout

### `/<path>`

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

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Node

Browser

Config

Mount mode

VFS.md

Virtual Filesystem

VFS Layout

`/<path>`

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

​Node

​Browser

​Config

​Mount mode

​VFS.md

​Virtual Filesystem

​VFS Layout

/<path>

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

Node

Browser

Config

Mount mode

VFS.md

Virtual Filesystem

VFS Layout

`/<path>`

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS