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

# Logs and labels

> Read a machine's console log and recent operations, and tag machines with key=value labels.

Read a machine's logs when it does not boot, is unreachable, or failed to start or resume. Tag machines
with labels to find them again.

## Read a machine's logs

`instabox logs` prints a machine's console log and its last 20 operations (create, start, stop, pause,
and resume, with their errors). Reading the log works in every state and never wakes the machine.

```bash theme={null}
instabox logs job                 # the last 200 console lines and the operations
instabox logs job --tail 50 -f    # follow new output (Ctrl-C stops)
instabox logs job --json          # GET /v1/machines/{id}/logs
```

The console log is the serial console: kernel and systemd boot messages, anything written to
`/dev/console`, and errors from the VM monitor. The host keeps the last 8 MiB across stops, pauses, and
restarts.

A command's own output is kept with its background job. To read the full guest journal, run
`journalctl` over exec.

```bash theme={null}
instabox jobs logs job <job-id>
instabox exec job -- sudo journalctl -b --no-pager   # this boot
```

> [accordion] Over the API
>
> `GET /v1/machines/{id}/logs?tail=N` (scope `machines:read`) returns `console`, `cursor`, `state` and
> `operations` (oldest first). To follow it, pass `cursor` as `after` on the next request to get only
> newer output. When the console cannot be read, for example because the machine's disks are in
> storage, the response is still `200`, with `consoleUnavailable` and the operations.

## Labels

Give a machine up to 32 `key=value` labels (`metadata` in the API), then filter by them.

```bash theme={null}
instabox create --name job --meta task=review
instabox ls --meta task=review     # GET /v1/machines?metadata=task:review
```

With several `--meta` flags, a machine must match all of them. The server filters, and lists only your
own orgs' machines. An agent can tag every machine it creates with `--meta session=ID` and find them
later with `instabox ls --meta session=ID`.

> [!WARNING]
>
> Labels are stored in plain text. Use them for labels, not secrets.

The key and value limits are under `metadata` in [Create parameters](https://instabox.sh/docs/machines/sizes.md#create-parameters).