Set up people and the on-call schedule
Who acts: an administrator with sudo on the MMHotline server, or that
person's coding agent.
When to use this page: to add or remove a person, change a person's role, or choose who is on call and when.
What this page does: you list the team's people and the on-call schedule in the settings file, preview the schedule, and apply both.
Terms:
- The person on call is the one an SOS wakes first. The backup is woken next if nobody claims the SOS in time; after the backup, MMHotline wakes everyone else who is available.
- The time to claim is how long each of these steps waits for someone to claim the SOS before the next step, such as 5 minutes.
- A handoff is the moment on call passes to the next person.
Choose the route
| You want | Schedule type | Where |
|---|---|---|
| Each person on call for a week, in turn | weekly_rotation |
Steps |
| A fixed person for each weekday | day_of_week |
Other schedule types |
| A fixed person for each hour of the day, such as across time zones | hour_of_day |
Other schedule types |
| Anything else, such as holidays or a weekend person | custom_schedule_code |
Write a custom schedule |
| To cover for someone or be away for a while | none: no settings change | Be away or take over on call |
Before you start
- MMHotline is installed and behind Cloudflare Access, and you can change its settings file, as Change the settings says.
- Each new person can sign in through the team's Cloudflare Access application, and you know the email address that sign-in gives them. Reason: that address is how MMHotline knows who is signing in.
Steps
-
List the people. In the settings file,
peoplenames everyone who uses MMHotline, with at least one administrator:people: - name: Barbara Example sign_in_email_address: barbara@example.com role: administrator - name: Carlos Example sign_in_email_address: carlos@example.com role: member - name: Dana Example sign_in_email_address: dana@example.com role: membername: shown on pages and in alerts.sign_in_email_address: the address the person's Cloudflare Access sign-in gives. MMHotline stores it in lower case.role:administratorormember. Administrators also open the administration pages, such as Sending services, and see other people's contact methods.
To add a person and put them in the schedule, apply
peoplefirst, then change the schedule: the preview in step 4 knows only people already applied.Cloudflare Access decides who may reach MMHotline at all; this list decides who is on the team. Nobody needs an invitation or a password.
-
Write the schedule. For a weekly rotation:
on_call_schedule: escalate_if_unclaimed_after_minutes: 5 schedule_type: weekly_rotation time_zone: America/New_York handoff_hour: 9 handoff_minute: 0 handoff_weekday: 1 first_start_date: "2026-11-02" rotation_sign_in_email_addresses: [barbara@example.com, carlos@example.com, dana@example.com] backup_option: everyone_availableescalate_if_unclaimed_after_minutes: the time to claim, 1 to 60.time_zone: the schedule's time zone, such asEurope/Berlin. Handoffs follow its local time, also across daylight saving changes, and MMHotline's pages show times in it.handoff_hour,handoff_minute,handoff_weekday: the local handoff time, 0 to 23 and 0 to 59; weekday 0 is Sunday, 1 Monday.first_start_date: the date the first person in the list starts, on the handoff weekday.rotation_sign_in_email_addresses: the people in turn, each once. Each one must be inpeople.backup_option:everyone_available;next_in_rotation, the next person in the list, for a weekly rotation only; orfixed_person, withbackup_sign_in_email_address: barbara@example.com.
-
Check the file:
sudo mmhotline settings check --settings-file /etc/mmhotline/mmhotline_settings.ymlCheck: it says
The settings file /etc/mmhotline/mmhotline_settings.yml has no problems. -
Preview the schedule when it names only people already on the team:
sudo mmhotline schedules preview --settings-file /etc/mmhotline/mmhotline_settings.ymlCheck: it lists who is on call from each handoff, in UTC, and saves nothing:
At 2026-11-15T06:17:43Z, primary: carlos@example.com; backup option: everyone_available; backup: everyone available. At 2026-11-16T14:00:00Z, primary: dana@example.com; backup option: everyone_available; backup: everyone available. At 2026-11-23T14:00:00Z, primary: barbara@example.com; backup option: everyone_available; backup: everyone available.The first line is now; 14:00 UTC is 09:00 in New York. A schedule that names a person not yet applied is refused with
apply the settings file with those people first, because the preview uses the running team. -
Apply the file:
sudo mmhotline settings applyCheck: among the lines it prints are:
people: applied. on_call_schedule: applied.Then
sudo mmhotline schedules showends with who an SOS wakes now:On call now: Carlos Example (carlos@example.com). Backup now: everyone else available: Barbara Example (barbara@example.com), Dana Example (dana@example.com). -
Tell each new person to open MMHotline's address and sign in, then add a contact method that wakes them, as Add contact methods says. Until they do, an SOS cannot wake them.
Check: in MMHotline, On call shows the schedule: Week by week for a weekly rotation, Coming handovers for the other built-in types. Its folded Where the schedule is set shows what the settings file sets. People lists each person, email address, and role. The team on On call names each person with what can wake them at night, such as
Woken by Pushover notification. A person with nothing listed there cannot be woken.
Other schedule types
Replace the type's keys in on_call_schedule; the other keys stay.
-
By day of the week: 7 entries, a person for each weekday, Sunday first, with one handoff time. A Monday entry with a 09:00 handoff lasts until Tuesday at 09:00. Use
""for a day with nobody scheduled.schedule_type: day_of_week handoff_hour: 9 handoff_minute: 0 assignment_sign_in_email_addresses: [carlos@example.com, barbara@example.com, barbara@example.com, barbara@example.com, barbara@example.com, barbara@example.com, carlos@example.com] backup_option: fixed_person backup_sign_in_email_address: barbara@example.com -
By hour of the day:
schedule_type: hour_of_dayandassignment_sign_in_email_addresseswith 24 entries, hour 0 first, the same every day. It has no handoff keys.
A time with nobody scheduled shows No one scheduled and wakes the backup first, then everyone available; the previous person is not kept. If nobody at all is available, an SOS wakes every person. Handoffs follow the time zone's daylight saving changes, as timezones and daylight-saving time describes.
What a change does
- A schedule change affects new SOS alerts and the next escalation steps. An incident someone already claimed stays theirs, and a person an open SOS is waking now keeps their time to claim.
- A changed name or role takes effect when the file is applied.
- Removing a person: leave them out of
peopleand of the schedule, and apply. Their browser access ends on their next request, their sign-in links stop working, their contact methods are removed, and queued notifications to them are cancelled; a phone call already placed cannot be recalled. Their name stays in history.
sudo mmhotline people list lists the people, and
sudo mmhotline people create-sign-in-link makes a sign-in link, as the
people command reference says.
If something is different
- The check says
on_call_schedule.rotation_sign_in_email_addresses[2]: erin@example.com is not the sign-in email address of any person listed in people: add the person topeople, or fix the address. - The check says
on_call_schedule: the first start date must be a date such as 2026-11-02 on the handoff weekday (0 is Sunday): choose afirst_start_dateon thehandoff_weekday. - The apply says
people: did not apply: Dana Example owns 1 claimed incident. Resolve the claimed incidents or have someone take over the claimed incidents before removing the person.Reason: removing the person would leave the incident with nobody. Resolve it, or take it over as Handle an incident says, then apply again. The same happens while the person has taken on call: give it back to the schedule first, as Be away or take over on call says. The other parts of the file still apply, and the earlier people stay. - A person cannot sign in: their
sign_in_email_addressmust match the address their Cloudflare Access sign-in gives exactly, apart from letter case.
This page is docs/how-to/set-up-people-and-the-on-call-schedule.md in the MMHotline repository.