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

# Langfuse

> Virtualize a Langfuse project from Node or the browser.

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

## Install

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

## Configure

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

const langfuse = new LangfuseVFS({
  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
  secretKey: process.env.LANGFUSE_SECRET_KEY!,
  host: process.env.LANGFUSE_HOST!,
})
const ws = new Workspace({ '/langfuse': langfuse }, { mode: MountMode.READ })

const result = await ws.shell('ls /langfuse/traces && ls /langfuse/prompts')
console.log(result.stdoutText)
await ws.close()
```

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

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

**publicKey** `string` *required*

Langfuse project public key.

**secretKey** `string` *required*

Langfuse project secret key.

**host** `string` (default: '[https://cloud.langfuse.com](https://cloud.langfuse.com)')

Langfuse API host; override for a self-hosted or regional instance.

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

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

```text theme={null}
/langfuse/
  traces/
    <trace-id>.json
  sessions/
    <session-id>/
      <trace-id>.json
  prompts/
    <prompt-name>/
      1.json
      2.json
  datasets/
    <dataset-name>/
      items.jsonl
      runs/
        <run-name>.jsonl
```

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

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

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

const langfuse = new LangfuseVFS({
  publicKey: LANGFUSE_PUBLIC_KEY,
  secretKey: LANGFUSE_SECRET_KEY,
})
const ws = new Workspace({ '/langfuse': langfuse }, { mode: MountMode.READ })
```

* The secret key reaches the page, so anyone who loads it can read the project.

## VFS.md

The [VFS.md](https://docs.mirage.strukto.ai/home/setup/vfs-md.md) an agent reads with Langfuse mounted at `/<path>`.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `langfuse`, read |
>
> **VFS Layout**
>
> **`/<path>`**
>
> ```text theme={null}
> /<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.

> [tab] Raw
>
> ````markdown theme={null}
> ---
> 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.
> ````


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