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

# Command Logs

> What Mirage records about each line a session runs, where it keeps it, and how to send it to an OpenTelemetry backend as traces.

Mirage records every line a session runs. A line is what you type, split the
way bash splits it, so `cd /data; wc -l notes.txt` is one line. For each line,
Mirage records the line, its exit code, the first 4096 characters of its
stdout and stderr, and the reads and writes it made to a mount, such as `wc`
reading a file. Mirage does not record every mount call yet. A `stat`, a
directory listing, a delete or a move may leave no record.

Mirage keeps these records as command logs and serves them back to you, to
the agent and to policies. If your process sets up an OpenTelemetry SDK,
Mirage also sends each line to your tracing backend as a trace.

A session runs a line

↓→

Miragerecords it

↓→

Command logskept by Mirage in memory or on disk, read with `history`, `/.bash_history`, `mirage workspace logs` or `ws.history()`

Tracessent through your OpenTelemetry SDK to a backend such as Datadog, Honeycomb, Grafana or Langfuse

## Logs or traces

| | Command logs | Traces |
| - | - | - |
| Where they live | In Mirage, in memory or on disk | In your OpenTelemetry backend |
| Default | On | Off until your process sets up an OpenTelemetry SDK |
| How to read them | `history`, `/.bash_history`, `mirage workspace logs`, the logs API and `ws.history()` | Your tracing tool |
| Output kept | The first 4096 characters of stdout and stderr | The first 16 KiB of each by default |
| Mount calls | Every recorded call | Only a call made through `ws.vfs` or a FUSE mount |
| Jobs and processes | Only the line that started them | A `job` or `process` span for each |
| Several machines | Each machine keeps its own | All machines send to one backend |

Use command logs when the agent, a policy or you need to look back at what a
workspace ran. Use traces to watch many machines in one place, with your
tracing tool's search, retention and alerts.

## Example

This config mounts a RAM folder at `/data`.

```yaml demo.yaml theme={null}
mounts:
  /data:
    vfs: ram
    mode: write
```

Create a workspace named `demo` from it, and run three lines in it.

```bash theme={null}
mirage workspace create demo.yaml -w demo
mirage shell -w demo -c "printf 'a\nb\nc\n' > /data/notes.txt"
mirage shell -w demo -c "cd /data; wc -l notes.txt"
mirage shell -w demo -c "cat /data/missing.txt"
```

### The log entry

In a terminal, `mirage workspace logs -w demo` prints a table of lines, newest
first. Piped, it prints a JSON page whose `items` hold one entry per line.
`mirage workspace logs -w demo | jq '.items[1]'` prints the entry for the
second line. `cwd` is where the line started. `mounts`
has the read that `wc` made. The `cd` is not in `mounts`, because checking
that `/data` is a directory is a lookup.

```json theme={null}
{
  "id": "line_01a1ce07-038a-7061-8dec-17d364f9ec2b",
  "command": "cd /data; wc -l notes.txt",
  "cwd": "/",
  "started_at": "2026-11-12T04:32:08.587Z",
  "duration_ms": 12,
  "exit_code": 0,
  "stdout": "3 notes.txt\n",
  "stderr": "",
  "user_id": null,
  "api_key_id": null,
  "mounts": [
    {
      "op": "read",
      "path": "/data/notes.txt",
      "source": "ram",
      "bytes": 6,
      "started_at": "2026-11-12T04:32:08.596Z",
      "duration_ms": 0
    }
  ]
}
```

The entry for the failed `cat` has `"exit_code": 1` and the error in
`stderr`. Its `cwd` is `/data`, because the session kept the `cd` from the
line before.

### The raw records

Underneath, Mirage stores each line as records linked by `parent`: a
`command` record when the line starts, a `vfs` record for each recorded
mount call, and a `result` record when it ends.
`mirage workspace logs -w demo --jsonl` prints them, oldest first:

```json theme={null}
{"session":"01a1ce07-020a-7030-b097-92dc1f296149","timestamp":"2026-11-12T04:32:08.587Z","cwd":"/","type":"command","id":"line_01a1ce07-038a-7061-8dec-17d364f9ec2b","command":"cd /data; wc -l notes.txt"}
{"session":"01a1ce07-020a-7030-b097-92dc1f296149","timestamp":"2026-11-12T04:32:08.596Z","cwd":"/data","type":"vfs","parent":"line_01a1ce07-038a-7061-8dec-17d364f9ec2b","vfs":"read","path":"/data/notes.txt","source":"ram","bytes":6,"duration_ms":0}
{"session":"01a1ce07-020a-7030-b097-92dc1f296149","timestamp":"2026-11-12T04:32:08.599Z","cwd":"/data","type":"result","parent":"line_01a1ce07-038a-7061-8dec-17d364f9ec2b","duration_ms":12,"exit_code":0,"stdout":"3 notes.txt\n","stderr":""}
```

`await ws.history(vfs=True)` in Python, or `await ws.history({ vfs: true })`
in TypeScript, returns the same records, with `timestamp` in epoch
milliseconds instead of a date string.

### The trace

If the process that runs the workspace has an OpenTelemetry SDK set up (see
[Trace setup](#trace-setup)), the same line also becomes one trace with two
spans. The `shell` span covers the whole line, and the `process` span sits
under it. The file `wc` read stays in the command log: a line's calls to
mounts are its commands' own work.

```text theme={null}
shell       cd /data; wc -l notes.txt   exit 0, 3 ms
└─ process  cd /data; wc -l notes.txt   exit 0
```

A call your code makes to a mount itself, through `ws.vfs` or a
[FUSE mount](https://docs.mirage.strukto.ai/home/setup/fuse.md), is a `vfs.<call>` span of its own,
such as `vfs.read`:

```text theme={null}
vfs.read    /data/notes.txt   6 bytes
```

The `shell` span carries the line's id as `mirage.line.id`, so you can
match a trace to its log entry. The span below comes from a separate run, so
its ids differ from the entry above.

```json theme={null}
{
  "mirage.line.id": "line_01a1cdf9-3be7-7031-b296-54aee757276e",
  "mirage.session.id": "01a1cdf9-3bda-7096-b1e2-09c35bd65da4",
  "mirage.command": "cd /data; wc -l notes.txt",
  "mirage.timestamp": 1794457025511,
  "mirage.workspace.id": "demo",
  "host.name": "my-laptop",
  "mirage.cwd": "/",
  "mirage.exit_code": 0,
  "mirage.duration_ms": 3,
  "mirage.stdout": "3 notes.txt\n",
  "mirage.stderr": ""
}
```

## Reading logs

| Where | What it returns |
| - | - |
| `history` | The session's newest 500 lines, as bash's `history` lists them. |
| `/.bash_history` | The session's newest 10,000 lines, as a file. [Policies](https://docs.mirage.strukto.ai/home/policy/policies.md) read the logs from this file. |
| `mirage workspace logs` | Entries for finished lines, newest first, one page at a time. `--jsonl` prints the records of every finished line, oldest first. See the [CLI reference](https://docs.mirage.strukto.ai/home/access/cli.md). |
| `GET /v1/workspaces/{id}/logs` | The same pages over HTTP. See [List workspace logs](https://docs.mirage.strukto.ai/api/operations/workspaces/list-workspace-logs.md). |
| `ws.history()` | The `command` and `result` records from every session, oldest first, at most the newest 10,000. Pass `vfs=True` in Python, or `{ vfs: true }` in TypeScript, to add the `vfs` records. It is async in both languages, so `await` it. |

`mirage shell --no-record` runs a line without logging it.

## Log entries

Mirage splits input into lines the same way bash does, and logs one entry
per line.

| Input | Mirage logs |
| - | - |
| `cd /data; wc -l notes.txt` | One entry, with the output of both commands. |
| `echo x
echo y` | Two entries, `echo x` and `echo y`. |
| `echo p
exit 2
echo q` | Two entries, `echo p` and `exit 2`. `echo q` never runs, so Mirage does not log it. |
| `for f in a b
do
  echo $f
done` | One entry. In an interactive terminal, Mirage joins the lines as bash does, into `for f in a b; do echo $f; done`. |
| `cat <<EOF
hello
EOF` | One entry that keeps the heredoc body. |
| `mirage shell --no-record \
  -c "echo hidden"` | No entry. |

A `set -e` failure stops a line the same way `exit` does. If a
`post_execute` [policy](https://docs.mirage.strukto.ai/home/policy/policies.md) checks a line, Mirage writes
the entry after the policy answers. Output that the policy drops never
reaches the logs.

## Log storage

By default, a workspace you build in code keeps its logs in memory. A
workspace the server builds keeps them on disk under `~/.mirage/state`.

To choose, set `store.logs` to one of these backends.

| `type` | Storage | Options |
| - | - | - |
| `ram` | The process memory, up to 8 MB. Mirage drops the oldest entries first, and the logs end when the process exits. | None |
| `disk` | Files under `root`. | `root`, default `~/.mirage/state` |

`store.logs` lets the logs live apart from the rest of the workspace state.
This config keeps the state on Redis and the logs on local disk.

> [tab] YAML
>
> ```yaml theme={null}
> workspace_id: agent
> store:
>   type: redis
>   url: redis://redis.internal:6379/0
>   logs:
>     type: disk
>     root: /var/lib/mirage
> ```

> [tab] Python
>
> ```python theme={null}
> from mirage import Workspace
> from mirage.workspace.store import DiskWorkspaceStateStore, RedisWorkspaceStateStore
>
> store = RedisWorkspaceStateStore(
>     url="redis://redis.internal:6379/0",
>     logs=DiskWorkspaceStateStore(root="/var/lib/mirage"),
> )
> ws = Workspace(mounts, workspace_id="agent", store=store, owns_store=True)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { DiskWorkspaceStateStore, RedisWorkspaceStateStore, Workspace } from '@struktoai/mirage-node'
>
> const store = new RedisWorkspaceStateStore({
>   url: 'redis://redis.internal:6379/0',
>   logs: new DiskWorkspaceStateStore({ root: '/var/lib/mirage' }),
> })
> const ws = new Workspace(mounts, { workspaceId: 'agent', store, ownsStore: true })
> ```

Without `store.logs`, the logs go where `store.type` points. Redis does not
hold logs, so with `store.type: redis` they go to disk under the store's
`root`.

## Restarts

Each log belongs to a session. A rebuilt workspace shows a session's logs
only after it has that session again. To keep logs across a restart, do one
of these.

* Keep the [sessions](https://docs.mirage.strukto.ai/home/infrastructure/sessions.md) on a store that
  survives a restart.
* Give the default session a fixed id with `default_session_id`.

## Trace setup

Mirage sends nothing until your process sets up an OpenTelemetry SDK. Mirage
depends only on the OpenTelemetry API, so install the SDK and an exporter
yourself. The exporter picks the backend. Set up the SDK before the
workspace runs its first line.

> [tab] Python
>
> **Set up the SDK in code.**
>
> ```python agent.py theme={null}
> import asyncio
>
> from opentelemetry import trace
> from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
> from opentelemetry.sdk.trace import TracerProvider
> from opentelemetry.sdk.trace.export import BatchSpanProcessor
>
> from mirage import RAMVFS, MountMode, Workspace
>
> # Set up the OpenTelemetry SDK before the workspace runs a line.
> provider = TracerProvider()
> provider.add_span_processor(
>     BatchSpanProcessor(OTLPSpanExporter(endpoint="https://otlp.example.com/v1/traces"))
> )
> trace.set_tracer_provider(provider)
>
> # No tracing code here. Mirage finds the SDK on its own.
> async def main():
>     ws = Workspace({"/data": RAMVFS()}, mode=MountMode.WRITE, workspace_id="demo")
>     await ws.shell("echo hi > /data/a.txt; cat /data/a.txt")
>     await ws.close()
>
> asyncio.run(main())
> # Send the last spans before the process exits.
> provider.shutdown()
> ```
>
> ```bash theme={null}
> pip install mirage-ai opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
> python agent.py
> ```
>
> **Or run without code changes.** `opentelemetry-instrument` sets up the
> SDK for you.
>
> ```python agent.py theme={null}
> # No tracing code here. opentelemetry-instrument sets up the SDK.
> import asyncio
>
> from mirage import RAMVFS, MountMode, Workspace
>
> async def main():
>     ws = Workspace({"/data": RAMVFS()}, mode=MountMode.WRITE, workspace_id="demo")
>     await ws.shell("echo hi > /data/a.txt; cat /data/a.txt")
>     await ws.close()
>
> asyncio.run(main())
> ```
>
> ```bash theme={null}
> pip install mirage-ai opentelemetry-distro opentelemetry-exporter-otlp
>
> # opentelemetry-instrument sets up the SDK from the OTEL_* variables
> # before agent.py starts. Without OTEL_EXPORTER_OTLP_PROTOCOL, the
> # exporter uses gRPC instead of HTTP.
> OTEL_TRACES_EXPORTER=otlp \
> OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
> OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.example.com \
>   opentelemetry-instrument python agent.py
> ```

> [tab] TypeScript
>
> ```typescript agent.ts theme={null}
> import { trace } from '@opentelemetry/api'
> import { BatchSpanProcessor, TracerProvider } from '@opentelemetry/sdk-trace'
> import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
> import { MountMode, RAMVFS, Workspace } from '@struktoai/mirage-node'
>
> // Set up the OpenTelemetry SDK before the workspace runs a line.
> const provider = new TracerProvider({
>   spanProcessors: [
>     new BatchSpanProcessor({
>       exporter: new OTLPTraceExporter({ url: 'https://otlp.example.com/v1/traces' }),
>     }),
>   ],
> })
> trace.setGlobalTracerProvider(provider)
>
> // No tracing code here. Mirage finds the SDK on its own.
> const ws = new Workspace({ '/data': new RAMVFS() }, { mode: MountMode.WRITE, workspaceId: 'demo' })
> await ws.shell('echo hi > /data/a.txt; cat /data/a.txt')
> await ws.close()
> // Send the last spans before the process exits.
> await provider.shutdown()
> ```
>
> ```bash theme={null}
> # Mirage needs @opentelemetry/api 1.10 or later. Use the 3.x @opentelemetry/sdk-trace:
> # the older @opentelemetry/sdk-trace-base 2.x allows only API versions below 1.10.
> npm install @struktoai/mirage-node @opentelemetry/api @opentelemetry/sdk-trace @opentelemetry/exporter-trace-otlp-http
>
> # Node 22.20 or later runs TypeScript files directly.
> node agent.ts
> ```

## Join a caller's trace

Send the caller's W3C trace context with a line and its `shell` span goes
under the caller's span, so your service's spans and Mirage's land in one
trace. Each access carries it the standard way:

| Access | Where the trace context goes |
| - | - |
| In-app | The OpenTelemetry context current when you call `ws.shell` |
| HTTP, RPC | The `traceparent` header |
| MCP | `_meta.traceparent` on `tools/call` |
| CLI, `mirage mcp`, `mirage rpc` | The `TRACEPARENT` environment variable |
| SSH | `TRACEPARENT`, sent with `ssh -o SetEnv=TRACEPARENT=...` |

```bash theme={null}
TRACEPARENT=00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01 mirage shell -w demo -c 'cat /data/a.txt'
```

`tracestate` travels the same way. A line without a trace context starts
a trace of its own. In TypeScript, the process running the
workspace needs a context manager and the W3C propagator; `NodeSDK`
registers both.

## Spans

Each line's spans form one tree: the `shell` span and everything it
started. A process sits under the process that started it, and a background
job's process under its `job` span. Use the span and attribute names in your
backend's queries, dashboards and alerts.

| To find | Filter on |
| - | - |
| Failed lines | `shell` spans where `mirage.exit_code` is not 0 |
| One agent's run | Any span with a given `mirage.session.id` |
| Killed programs | `process` spans with a `mirage.signal` |

> [accordion] All spans and attributes
>
> | Span | Sent | Attributes |
> | - | - | - |
> | `shell` | When a typed line ends | `mirage.line.id`, `mirage.workspace.id`, `mirage.session.id`, `host.name`, `mirage.command`, `mirage.cwd`, `mirage.exit_code`, `mirage.timestamp`, `mirage.duration_ms`, `mirage.stdout`, `mirage.stderr` |
> | `vfs.<call>` | For each call your code makes to a mount itself, through `ws.vfs` or a FUSE mount, such as `vfs.read` | `mirage.vfs.path`, `mirage.vfs.source`, `mirage.vfs.bytes`, `mirage.vfs.timestamp`, `mirage.vfs.duration_ms`, `mirage.session.id`, `mirage.workspace.id`, `host.name` |
> | `job` | When an `&` job ends | `mirage.job.id`, `mirage.job.number`, `mirage.line.id`, `mirage.workspace.id`, `mirage.session.id`, `host.name`, `mirage.machine.type`, `mirage.machine.name`, `mirage.machine.id`, `process.pid`, `mirage.process.pid`, `mirage.command`, `mirage.cwd`, `mirage.exit_code`, `mirage.signal` |
> | `process` | When a process the line started ends | `process.pid`, `mirage.process.pid`, `process.parent_pid`, `process.group_leader.pid`, `mirage.line.id`, `mirage.workspace.id`, `mirage.session.id`, `host.name`, `mirage.machine.type`, `mirage.machine.name`, `mirage.machine.id`, `process.command_line`, `mirage.cwd`, `process.exit.code`, `mirage.signal`, `mirage.error`, and a link to each process it read from, with `mirage.input` |

## Span attributes

| Attribute | Meaning |
| - | - |
| `host.name` | The hostname of the host that runs Mirage, such as `my-laptop`. |
| `mirage.machine.type` | The provider of the [machine](https://docs.mirage.strukto.ai/home/setup/machine/overview.md) a job or process ran on, such as `e2b` or `docker`, and `host` for the host that runs Mirage. |
| `mirage.machine.name` | The machine's name under `machines:`, such as `gpu`, or the hostname for Mirage's own processes. With the type it makes the machine's full name elsewhere in Mirage, such as `e2b:gpu` or `host:laptop`. |
| `mirage.machine.id` | What the provider calls the machine: the sandbox id for E2B and Daytona, the container for Docker, the pod for Kubernetes, the host for SSH, the hostname for a `host` machine. |
| `process.pid` | The pid the agent sees in `ps` and `$!`: a program's own pid on its machine, else Mirage's number for the process. |
| `mirage.process.pid` | Mirage's own number for the process, the same as `process.pid` for a command Mirage runs itself. |
| `mirage.cwd` | The directory the line started in. |
| `mirage.timestamp` | The span's start, in milliseconds. It repeats the span's own time for tracers that can't set it, such as Cloudflare Workers custom spans. `mirage.duration_ms` does the same for its length. |
| `mirage.vfs.timestamp` | When the mount call ended, in milliseconds. |
| `mirage.input` | On a link from a `process` span to the process whose output it read: `stdin` for the stage before it in a pipe, the `/dev/fd` path a `<(...)` gave it, such as `/dev/fd/63`, or `argv` for a `$(...)` in its arguments. |

Traces cover what runs in the workspace and on its machines. A program that a
machine runs on another host sends no spans of its own.

## Trace limits

| Setting | Default | Effect |
| - | - | - |
| `MIRAGE_TRACE_CONTENT_MAX_BYTES` | 16 KiB | How much of the output `mirage.stdout` and `mirage.stderr` each keep, as UTF-8 text. The default fits the 64 KB that a Cloudflare Workers span allows for all its attributes. |
| `MIRAGE_TRACE_CAPTURE_CONTENT` | `true` | Set to `false` to keep output and mount calls out of traces. `shell` spans then carry no output, and Mirage sends no `vfs.<call>` spans. |

## Next steps

* See every `store` setting, `logs` included, in the [configuration reference](https://docs.mirage.strukto.ai/home/configuration/workspace.md).
* Check lines before or after they run with [policies](https://docs.mirage.strukto.ai/home/policy/policies.md), which read `/.bash_history`.
* See every `mirage workspace logs` flag in the [CLI reference](https://docs.mirage.strukto.ai/home/access/cli.md).


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