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.

Terminal
marfa attention
nothing needs attention

To 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:

Terminal
marfa metrics
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 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:

Terminal
marfa housekeeping list
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.

JobRuns everyWhat it doesHeld while the clock is ahead
event-log-cleanuphourRemoves expired event log entries and idempotency records.yes
audit-cleanupdayRemoves expired audit entries and outbound webhook delivery history.yes
inbound-delivery-cleanupminuteRemoves inbound deliveries after their handled or pending retention window.yes
heartbeatminutePings the liveness receiver heartbeat_url names.no
version-thinninghourThins item versions according to the configured retention policy.yes
feed-expiryhourMoves expired feed items to the trash.yes
trash-purgedayPermanently removes items whose trash retention has elapsed.yes
credential-cleanuphourRemoves 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-replicateminuteCopies each blob into every attached store that lacks it.no
blob-integrityhourChecks blob copies and removes copies whose bytes are missing or altered.no
blob-orphansdayReports unreferenced blobs and purges them after the grace period.yes
enrichment-sweep30 secondsExtracts searchable text and image dimensions from uploaded files.no
attention-check5 minutesChecks what needs the owner's attention and announces each new entry (events/attention-raised).no
bulk-action-gchourRemoves finished bulk action jobs after 7 days.yes
table-row-cleanuphourRemoves 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-check6 hoursAsks GitHub for the newest published Marfa release and keeps what it finds (updates.md).no
backupbackup_interval_secondsPuts 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-purge

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:

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. The rules behind this page are in the housekeeping chapter of the contract.

On this page