# Check an instance's health (/run/check-health)

Check from any computer that your instance is well, how much it uses and what its housekeeping jobs last did, and run one now.



An instance looks after itself on a schedule: it thins old versions, empties the bin, clears old logs, copies files and takes backups. **Check that it is keeping up** from any computer with the CLI signed in, using a credential that holds `instance.read`.

## Check that all is well [#check-that-all-is-well]

**`marfa attention` is the one check to run.** It names a degraded part of the server, a job that failed, a connector or folder with a problem, a key about to expire, and backups that aren't kept or have stopped. It prints `nothing needs attention` while all is well.

```bash
marfa attention
```

Output:

```text
nothing needs attention
```

**To hear of a new entry without asking,** [subscribe a webhook to `attention.raised`](/run/telemetry#see-a-fault-yourself). It hears one even while every database write fails, such as a full disk, because the attention check still runs then.

Two more checks fill it in. `marfa update status` says whether a newer release is out: read [Upgrade an instance](/run/upgrade) before you move to one. On the server's own computer, `marfa server status` says whether the service runs and answers, its release, and whether backups are kept, and shows the end of the log when the server isn't answering.

## See what an instance uses [#see-what-an-instance-uses]

`marfa metrics` asks the instance what it holds and what its process costs:

```bash
marfa metrics
```

Output:

```text
items.total                    4
blobs.total_bytes              15
process.memory_rss_bytes       39796736
process.memory_rss_peak_bytes  41320448
storage.database_bytes         1036288
storage.wal_bytes              688072
```

**`process.memory_rss_peak_bytes` is the most memory the process has held since it started:** compare it with the computer's memory after a large upload. `storage.database_bytes` and `storage.wal_bytes` are the database and its write-ahead log, and `blobs.total_bytes` is every file the instance keeps. A figure the server can't read is `null`. [Get instance metrics](/reference/api/health-and-maintenance/getInstanceMetrics) lists every field.

## See what the jobs did [#see-what-the-jobs-did]

Each piece of housekeeping is a job. **What each last did shows whether the instance is keeping up.** Listing needs `instance.read`, and running one needs `instance.maintain`:

```bash
marfa housekeeping list
```

Output:

```text
name        every  next run                  last run                            result
trash-purge 1 d    2026-11-22T03:50:41.331Z  succeeded 2026-11-21T03:50:41.331Z  {"deleted":0}
```

The result holds the job's own counts. A job whose last outcome is `failed`, with the reason in `last_error`, or whose next run is long past, is **the place to look when an instance falls behind.** `held` means the job did nothing because the clock is far ahead or a restore holds writes. `--json` gives every field.

| Job | Runs every | What it does | Held while the clock is ahead |
| - | - | - | - |
| `event-log-cleanup` | hour | Removes expired event log entries and idempotency records. | yes |
| `audit-cleanup` | day | Removes expired audit entries and outbound webhook delivery history. | yes |
| `inbound-delivery-cleanup` | minute | Removes inbound deliveries after their handled or pending retention window. | yes |
| `heartbeat` | minute | Pings the liveness receiver `heartbeat_url` names. | no |
| `version-thinning` | hour | Thins item versions according to the configured retention policy. | yes |
| `feed-expiry` | hour | Moves expired feed items to the trash. | yes |
| `trash-purge` | day | Permanently removes items whose trash retention has elapsed. | yes |
| `credential-cleanup` | hour | Removes expired sign-in sessions, codes and tokens, retires application grants not used within the inactivity window, removes revoked grants and unused registered clients after their retention windows, removes revoked or expired keys after their retention window, and removes connector mapping previews that have expired. | yes |
| `blob-replicate` | minute | Copies each blob into every attached store that lacks it. | no |
| `blob-integrity` | hour | Checks blob copies and removes copies whose bytes are missing or altered. | no |
| `blob-orphans` | day | Reports unreferenced blobs and purges them after the grace period. | yes |
| `enrichment-sweep` | 30 seconds | Extracts searchable text and image dimensions from uploaded files. | no |
| `attention-check` | 5 minutes | Checks what needs the owner's attention and announces each new entry (`events/attention-raised`). | no |
| `bulk-action-gc` | hour | Removes finished bulk action jobs after 7 days. | yes |
| `table-row-cleanup` | hour | Removes the rows and change logs of purged items, the batches of a table's change log older than `row_log_retention_days`, and rewrites the order a table keeps after its `order` changed and the search index of its rows after what it marks searchable changed, a page at a time. | yes |
| `release-check` | 6 hours | Asks GitHub for the newest published Marfa release and keeps what it finds (`updates.md`). | no |
| `backup` | `backup_interval_seconds` | Puts a backup of the instance in the backup folder or the object store when anything it holds has changed, and thins this instance's backups. | no |

Retention windows are [stored settings](/run/settings), such as `trash_retention_days`, and a change applies without a restart. **A retention of `0` keeps everything** of its kind. Four jobs are listed only while their setting is on: `heartbeat`, `blob-orphans`, `backup` and `release-check`.

To run a job now, name it. The server runs it before it answers, and a run that fails still answers `200` with `outcome` set to `failed`:

```bash
marfa housekeeping run trash-purge
```

## When the clock jumps ahead [#when-the-clock-jumps-ahead]

**While the server's clock reads more than seven days later than the time it last trusted, the jobs that delete do nothing.** A clock set wrong would otherwise judge everything old enough to remove. Those runs are recorded as `held`, and `marfa attention` names the hold. If the clock is right, as after months switched off, confirm it:

```bash
marfa housekeeping confirm-clock
```

An agent at `/mcp/admin` does this with `marfa_maintain`. To empty the bin now, see [Work from the command line](/use/command-line#get-an-item-back-or-empty-the-bin). The rules behind this page are in the [housekeeping](https://github.com/withmarfa/marfa/blob/main/conformance/spec/housekeeping.md) chapter of the contract.
