Check an instance's 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
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.
marfa attentionnothing needs attentionTo hear of a new entry without asking, subscribe a webhook to attention.raised. 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 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
marfa metrics asks the instance what it holds and what its process costs:
marfa metricsitems.total 4
blobs.total_bytes 15
process.memory_rss_bytes 39796736
process.memory_rss_peak_bytes 41320448
storage.database_bytes 1036288
storage.wal_bytes 688072process.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 lists every field.
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:
marfa housekeeping listname 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, 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:
marfa housekeeping run trash-purgeWhen 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:
marfa housekeeping confirm-clockAn agent at /mcp/admin does this with marfa_maintain. To empty the bin now, see Work from the command line. The rules behind this page are in the housekeeping chapter of the contract.