> ## Documentation Index
> Fetch the complete documentation index at: https://docs.microsandbox.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Logs

> Capture, read, and diagnose sandbox output

Every sandbox records captured output to disk so you can read it later, even after the sandbox stops or crashes. Use `msb logs <name>` from the CLI or `logs()` from the SDK.

## Read logs

```bash theme={null}
msb logs devbox
msb logs devbox --tail 100
msb logs devbox -f
msb logs devbox --grep ERROR
msb logs devbox --json | jq 'select(.s == "stderr")'
```

The default output includes user-program `stdout`, `stderr`, and PTY output. Add system diagnostics when you need runtime or kernel logs:

```bash theme={null}
msb logs devbox --source system
msb logs devbox --source all
```

## Read from the SDK

<CodeGroup>
  ```rust Rust theme={null}
  let handle = Sandbox::get("web").await?;
  let entries = handle.logs(&LogOptions::default())?;
  ```

  ```typescript TypeScript theme={null}
  const handle = await Sandbox.get("web");
  const entries = await handle.logs();
  ```

  ```python Python theme={null}
  handle = await Sandbox.get("web")
  entries = await handle.logs()
  ```

  ```go Go theme={null}
  handle, err := m.GetSandbox(ctx, "web")
  entries, err := handle.Logs(ctx, m.LogOptions{})
  ```
</CodeGroup>

Use log options to filter at read time:

<CodeGroup>
  ```rust Rust theme={null}
  let recent = handle.logs(&LogOptions {
      tail: Some(50),
      sources: vec![LogSource::Stdout, LogSource::Stderr],
      ..Default::default()
  })?;
  ```

  ```typescript TypeScript theme={null}
  const recent = await handle.logs({
      tail: 50,
      sources: ["stdout", "stderr"],
  });
  ```

  ```python Python theme={null}
  recent = await handle.logs(tail=50, sources=["stdout", "stderr"])
  ```

  ```go Go theme={null}
  recent, err := handle.Logs(ctx, m.LogOptions{
      Tail: 50,
      Sources: []m.LogSource{m.LogSourceStdout, m.LogSourceStderr},
  })
  ```
</CodeGroup>

## Sources

| Source   | Meaning                                                         |
| -------- | --------------------------------------------------------------- |
| `stdout` | Captured from a non-interactive session's stdout                |
| `stderr` | Captured from a non-interactive session's stderr                |
| `output` | Captured from a PTY session, where stdout and stderr are merged |
| `system` | Lifecycle markers plus runtime and kernel diagnostics           |

Interactive sessions use a PTY, so stdout and stderr are merged before microsandbox receives them. Non-interactive `exec` calls keep the streams separate.

## Diagnostic flows

**Sandbox crashed**

```bash theme={null}
msb ls
msb logs <name>
msb logs <name> --source system
```

**Sandbox will not start**

```bash theme={null}
msb create --name nope ...
msb logs nope --source system
```

**Program produced no logs**

`msb create` only boots a sandbox. Run something with `msb run`, `msb exec`, or an SDK `exec` call to produce user-program output.

## On disk

Sandbox logs live under `<sandbox-dir>/logs/`:

| File              | Contents                                                  |
| ----------------- | --------------------------------------------------------- |
| `exec.log`        | User-program output as JSON Lines                         |
| `runtime.log`     | Sandbox runtime diagnostics                               |
| `kernel.log`      | Guest kernel and agent console output                     |
| `boot-error.json` | Structured startup failure details, when boot fails early |