Runbooks

How runbooks differ from scripts

A script is one body of commands run on many hosts, right now, and lost if the app closes mid-run. A runbook is a graph of steps. Each step waits for the steps it depends on, can retry on failure, and writes its result to a local event log before the next one starts. Runbooks use the engine from MangoFlow, built into MangoSSH, and run on your machine: there is no server involved.

Runbooks live in the Scripts page. Open Scripts from the Workspace sidebar, then click Runbooks in its rail. Saved runbooks are listed under it, marked ⏰ when a schedule is on and ⚡ when a trigger is on.

Build a runbook

1. Click + New Runbook. Enter a Name and an optional Description.

2. Optionally declare Inputs, one per line as name = default | prompt. See Inputs and step outputs.

3. Each step has an id (the box on the left, such as step1) and a type (the dropdown). Give steps short, meaningful ids like preflight or patch: you will see them in run history and use them in templates. Renaming a step updates every step that depended on it.

4. Fill in the step's fields. Required fields are marked *.

5. Under Runs after, click the chips of the earlier steps this one must wait for. A step with nothing ticked starts immediately. You can only depend on steps above, so the editor cannot create a loop.

6. Under On failure, set the attempts, the delay between them, and whether to keep going if it still fails.

7. Click + Add step for the next one, then Save. The save is refused, with the step number, if a required field is empty, an id repeats, or a cron expression does not parse.

The editor is a form, one card per step, not a drag-and-drop canvas. Dependencies are what define the graph.

Step types

These are all the step types MangoSSH offers. Host fields list your saved SSH hosts.

SSH steps sign in the same way scripts do, so the rules in Scripts apply: the host needs a saved password, a key, an agent or a secrets-manager login, and hosts using interactive (MFA) authentication only work while a terminal to them is open. Files attached to an SSH step are staged next to the command in a temporary folder; on a Windows host, attaching a file switches the step to PowerShell. SFTP steps obey a policy that blocks file transfer on the host.

Order, retries and failure

• Order comes only from Runs after. Steps without a dependency between them are independent branches. They do not run at the same moment: the engine works through ready steps one at a time. A branch that is waiting on a timer or an approval does not hold up the others, though. For real parallel work across hosts, use SSH · run on several hosts.
• Retries. In On failure, the first number is the total number of attempts, so 1 means no retry and 10 means up to nine retries. The second is the delay in seconds between attempts.
• When a step still fails, every step that depends on it is marked skipped. Independent branches carry on, and the run ends as failed.
• keep going if it still fails treats the failure as acceptable: steps that depend on it still run, and the run can end as completed.
• There is no if/else step. Branch on results inside a command, or use a failing step plus retries to mean “wait until this is true”.

Inputs and step outputs

Any text field in a step can contain {{ … }} placeholders, filled in just before the step runs:

When you click ▶ Run on a runbook with inputs, a dialog asks for each one, prefilled with its default. Scheduled runs use the defaults. A placeholder that cannot be resolved is left as written, so a typo shows up in the output rather than failing silently.

Approval gates

A Wait for approval step parks the run until someone approves it. Steps after the gate should list it under Runs after.

• When a run reaches the gate, MangoSSH shows a toast (“is waiting for approval”) and a count badge on Runbooks in the rail, wherever you are in the app.
• The Runbooks page shows a strip listing each waiting step with an Approve button. The same button, labelled Approve "<step id>", appears when you expand the run.
• There is no reject button. To say no, expand the run and click ■ Cancel run; the remaining steps are skipped.
• A gate can wait indefinitely, including across restarts. Approving after a restart starts the run moving again.

Approval happens in MangoSSH on this device. It is a pause for a human decision, not a sign-off by a separate approver.

Worked example: patch the web tier with an approval gate

This runbook checks three Ubuntu web servers, waits for you to approve, upgrades packages, reboots, and confirms each server answers SSH again. It assumes the SSH user can run apt-get and shutdown through sudo without a password.

1. Click + New Runbook. Name it Patch web tier. Under Inputs, enter:

   reason = monthly patching | Change ticket or reason

2. Step 1. Id preflight, type SSH · run on several hosts. Tick web-01, web-02 and web-03. Command:

   logger -t mangossh "patch run {{ $run_id }}: {{ $run_input.reason }}"
   df -h / | tail -1
   sudo -n apt-get update -qq
   apt list --upgradable 2>/dev/null | tail -n +2

3. Step 2. Id approve, type Wait for approval, signal name approved. Runs after: preflight.

4. Step 3. Id patch, SSH · run on several hosts, the same three hosts, Timeout (s) 1800. Runs after: approve. Command:

   sudo -n env DEBIAN_FRONTEND=noninteractive apt-get -y -q upgrade

5. Step 4. Id reboot, SSH · run on several hosts, same hosts, after patch. Command: sudo -n shutdown -r +1. Scheduling the reboot a minute out lets the command return cleanly instead of the connection dropping mid-step.

6. Step 5. Id settle, Wait for a fixed time, 150 seconds, after reboot.

7. Step 6. Id verify, SSH · run on several hosts, same hosts, after settle. Command: uptime. Under On failure, set 10 attempts, 30s apart. While a server is still booting, the step fails and retries, for up to about five minutes.

8. Click Save, then ▶ Run. Enter the change ticket when asked.

9. Expand the run in Recent runs. When preflight completes, read the pending updates in its output. If they look right, click Approve "approve". If not, click ■ Cancel run.

To make this a monthly job, tick Run on a schedule and enter 0 2 1 * * (02:00 on the first of the month). The scheduled run still stops at the gate and waits for you.

Schedules and triggers

A runbook can start by itself on a clock, on an event, or both. Both only work while MangoSSH is running, and both are checked every 30 seconds.

Run on a schedule

Tick Run on a schedule and enter a cron expression: five fields (min hour day month weekday) as in crontab, or six with seconds first. The form shows the next run as you type. A run missed while MangoSSH was closed fires once on the next launch, not once for every window it missed. Scheduled runs use the input defaults.

Run when something happens

Tick Run when something happens and choose a source under When. There are two:

The host-down trigger relies on Connection Health monitoring, and waits until it has probed hosts in the current session, so a host that was down yesterday does not fire at launch. The certificate trigger reads the same certificates as SSH certificates.

Host fields in the editor are pickers, so use trigger data in text fields: for example, a SSH · run a command step on a management box that runs logger -p user.crit "{{ $run_input.host_name }} down for {{ $run_input.down_secs }}s", or a script there that restarts the VM.

To stop a runbook firing on its own without deleting it, click ⏸ Disable on its card; ▶ Enable arms it again. The Schedules page lists scheduled runbooks next to scheduled scripts.

Run history

Each runbook card has an eye button to preview the steps without opening the editor, a terminal button for the output of all its past runs, a pencil to edit, ▶ Run and Delete. Deleting a runbook keeps its past runs in the log. Click a runbook in the rail to show only its runs.

• Recent runs is a console with one line per run: status (running, completed, failed, cancelled), start time, runbook and a short run id. Click a line to expand it.
• An expanded run lists each step's status (pending, running, waiting_timer, waiting_signal, completed, failed, skipped), its error, live output while it runs, and the full event history with timestamps. Host pills on a step open that host's audit log; each SSH step is recorded there like a script run.
• The icons above the console expand or collapse every run, copy the text, and open a full-size view.
• Activity in the rail is one searchable log of every runbook event and script run, filterable by runbook, event kind (Problems only, Run start/finish, Step events, Timers & approvals) and time window, with Export.

MangoSSH keeps at most the last 50 runs of each runbook, and nothing older than 30 days. Runs are filed under the runbook's name, so after a rename, earlier runs appear only in the all-runbooks view.

If MangoSSH closes mid-run

Reopen the Runbooks page. A banner reports the runs that stopped mid-flight, with a ▶ Resume button for each. Resuming never happens without you, because a runbook can reboot machines.

• Completed steps are not repeated. Timers keep their original deadline.
• A step that was executing when the app closed runs again from the start. Write commands that are safe to repeat (apt-get -y upgrade is; “append a line to a file” is not).
• A run parked at an approval gate does not need resuming: it appears in the approvals strip, and approving it continues the run.

Import and export

Export saves every runbook as one JSON file; Import adds the runbooks in such a file as new entries. Each one is checked on the way in, and a bad one is rejected by name. An imported schedule does not fire until you open that runbook and click Save, which arms it from that moment. Host fields hold host ids, so runbooks imported on another machine need their hosts picked again unless the host list came across too.

Troubleshooting