# Restarts, backups and cleanups

> One timetable for everything that happens on a clock, with warnings people see and a record of what was skipped.

Source: https://stygion.eu/docs/keystone/operations
Updated: 2026-10-09

Everything on a clock lives in `operations.toml` and on the Operations screen.
Four jobs — `restart`, `backup`, `announce`, `clean` — and each has a `when`.

`when = "off"` is off. Otherwise it is a schedule: `"every 1m"`, or a time of
day. `timezone` decides what "03:00" means; left empty it is the machine's.

**Running one by hand takes the same road as the clock** — the same warnings,
the same countdown, the same record. There is no quiet path that skips the part
where people are told.

## Restart

| Setting | What it does |
|---|---|
| `warn-at` | When to tell people. Default `15m, 5m, 1m, 30s, 10s`. |
| `after-uptime` | Restart once the server has been up this long. |
| `above-memory-percent` | Or once memory passes this. Default 85. |
| `below-tps` | Or once TPS falls under this. Zero means never on TPS. |
| `wait-for-empty` | Do not interrupt anybody: wait until the server is empty. |
| `wait-at-most` | But not forever. Default two hours. |
| `supervised` | Whether something outside will start the server again. `auto` works it out. |

**`supervised` is the setting that decides whether a restart is a restart or a
shutdown.** If nothing outside brings the process back — no systemd unit, no
panel, no `while true` — then stopping is all Keystone can do. `auto` detects
the usual cases; set it explicitly if your setup is unusual.

The scheduled restart no longer refuses itself on a server started from its own
directory (the game reported that directory as an empty string, and a process
told to start in `""` does not start). **A hand-run `/keystone operations
restart` no longer skips a healthy server** as "nothing to gain" — uptime, memory
and TPS are reasons for the clock, not conditions on an operator. Every other
operation keeps all its checks when run by hand, and one that throws or gives no
answer does not run. `restart.after-uptime`, `.above-memory-percent`,
`.below-tps` and `.wait-for-empty` take effect as soon as they are changed.

## Backup

Copies the world while the server runs, and keeps a thinning history:
`keep-everything-for` (default a day), then `keep-one-a-day-for` (a week), then
`keep-one-a-week-for` (ninety days). `keep-free-megabytes` is the floor — the
oldest go early rather than filling the disk.

A file that has not changed since the last copy is **hard-linked** to it instead
of written again, so a week of a 5 GB world does not cost thirty-five. Where the
filesystem will not do that, Keystone says so and copies.

`directory` defaults to `backups`, beside the world. **A backup on the same disk
is not a backup**; copy it somewhere else on your own schedule.

## Announce

`notices` is the rotation, and `when` is how often one goes out. For a rule, a
Discord invite, a reminder about voting.

## Clean

The one people are most afraid of, so it is the most careful.

It only runs when there is something to do: `over-entities` (default 1200) is
the count that makes it worth doing, and `below-tps` can make it conditional on
the server actually struggling. When neither is met it says so and skips — the
Operations screen shows those lines, which is why "skipped: only 15 entities
loaded" is a normal thing to see.

What it takes: `items`, `experience`, `arrows` — all on by default. What it
leaves: `hostile-mobs`, `passive-mobs`, `named`, `tamed` — all off by default,
so nobody's horse and nobody's named villager goes anywhere.

`keep-entities` and `keep-items` are the explicit exceptions, and the defaults
are the ones that would hurt: villagers, item frames, armour stands, boats, and
netherite and elytra on the ground. `merge-radius` stacks dropped items instead
of deleting them; `older-than` spares whatever was dropped a moment ago;
`warn-at` counts people down first.

## The screens people see

`screens` holds what is shown when somebody is kicked, banned, banned until a
date, or arrives while the server is closed or full — with `{reason}`, `{by}`,
`{until}` and `{left}` filled in. `appeal` is the address on the ban screen; in
detail under [moderation](/docs/keystone/moderation) and
[accounts](/docs/keystone/accounts), which add two of their own.

**Reserved places.** `join.reserved-places` keeps that many of the server's places
for whoever holds `keystone.join.reserved` (give it to a group, say the paid
ranks). An ordinary player is turned away once only those places are left, and
sees `screens.full-reserved`. Nobody is ever let past a ban to make room, because
the refusal happens earlier rather than the admission happening later.

## Alerts

`alerts.tps-below` and `alerts.memory-above-percent`, held for `must-last`
before anybody is told, then quiet for `quiet-for`. Where they go is
`discord.alerts.channel`.

## What it records

`metrics.keep-for` (default a week) is how long the numbers behind all this are
kept — what the Operations screen draws on, and what a load test compares
against.