Approvals and automatic runs
Sign approvals ahead of time so a gateway can carry out agreed kinds of change on named machines, including automatic and scheduled runs.
On this page
A signed approval is a yes given ahead of time: it allows kinds of action on named machines until a date, so work can run when nobody is watching — a nightly check, a rollout across thirty cameras. Without one, every change waits for a person, one command at a time. This page covers what an approval allows, what the gateway checks, automatic and scheduled runs, and the fix-and-retry loop; for one runbook by hand, see Runbooks.
The rule#
Two people decide, separately: the approver signs what is allowed, and the gateway’s owner decides whether signed approvals count on that gateway at all. A change runs under an approval only if both say yes, and nothing that deletes or powers off ever runs on a production machine from an approval.
Runs on its own vs asks first#
| Situation | Without a signed approval | With one that covers it |
|---|---|---|
| Reading a machine (logs, status, config) | Asks once per machine per conversation; on an unattended gateway, only if reads are allowed | Runs |
| A change on a machine in change mode | Asks, every command | Runs, logged under the approval |
| A change on a machine in observe mode | Refused | Refused: observe stays observe |
| Delete or power on a production machine | Asks, plus typing the name | Never runs from an approval |
| A kind above the gateway’s ceiling | Asks | Doesn’t run from the approval |
| An automatic or scheduled run | Dry run only: looks, changes nothing | Runs the steps, with checks |
Any change on a gateway running ysra serve alone |
Ysra asks you to sign an approval | Runs |
| Auto mode | Never answers any of this | — |
What an approval says#
An approval allows kinds of action on named machines until a date: for example, restart services on the cameras until 1 November. It lasts from 5 minutes to 90 days, and is waiting for your signature, signed, withdrawn or expired.
Kinds of action#
| Kind | Covers | For example |
|---|---|---|
| read | Looking: logs, status, configuration | cat, journalctl, systemctl status |
| service | Starting, stopping, restarting, enabling or disabling a service; stopping processes | systemctl restart, kill, supervisorctl |
| config | Changing files and settings | cp, sed, tee, crontab, sysctl |
| packages | Installing or removing software | apt, dnf, pip, npm |
| network | Firewall and network settings | iptables, ufw, ip, nmcli |
| containers | Running and managing containers; removing containers or images counts as delete | docker, podman, kubectl, helm |
| delete | Removing or wiping data | rm, shred, mkfs, dd |
| power | Reboot, shutdown, power off, halt, suspend, hibernate | reboot, shutdown, systemctl poweroff |
| users | Accounts and permissions | useradd, passwd, chmod, chown |
| access | SSH keys and SSH configuration, including authorized_keys and sshd_config |
ssh-keygen, ssh-copy-id |
| shell | Shells, running as another user, writing through redirection, anything the rules don’t recognise | bash, sudo, xargs |
The choices under “Ysra may”#
| Choice | Allows | Never allows |
|---|---|---|
| Read only | read | — |
| Restart services | read, service | — |
| Maintenance — no delete, no power | read, service, config, packages | delete, power |
| Everything except delete and power | read, service, config, packages, network, containers, users | delete, power |
| Only these commands… | One command per line; {name} stands for one plain word, as in systemctl restart {service} |
— |
“Never” always wins over “allows”. The gateway’s ceiling applies on top.
Sign an approval#
Signing is in the desktop app, with a key that stays in your computer’s keychain. The terminal can list and withdraw approvals; the web app and the phone don’t show them.
- Settings → Approvals → Make my approval key (once). The tab shows its Fingerprint and Public key, with Copy the commands for the gateway’s owner.
- The gateway’s owner trusts the key; see On the gateway.
-
In the Machines panel, open Approvals → New approval… and fill in Approve changes:
Field Options On A group, These machines, or The n selected Ysra may One of the choices above Until 1 hour from now, 8 hours from now, 1 day from now, 7 days from now, or Custom… up to 90 days Note (optional) What it is for -
Choose Prepare the approval. A card shows On, Commands, Never, Until, marked waiting for your signature. Nothing is allowed yet.
- Choose Approve with this computer’s key, then Approve in the confirmation dialog.
The thread records You approved: … Changes outside this still need your OK.
On the gateway#
A gateway ignores signed approvals until its owner turns them on.
| Command | What it does |
|---|---|
ysra approvers add <public key> --name "Sam's Mac" |
Trusts an approver’s key, after showing its fingerprint and asking |
ysra approvers list |
Who is trusted, and the settings |
ysra approvers rm <fingerprint or name> |
Stops trusting one |
ysra approvers runs on |
Carries out approved changes |
ysra approvers runs off |
Back to asking every time (the default) |
ysra approvers ceiling read,service,config |
The most this gateway ever allows from an approval |
Compare the fingerprint with the one under Settings → Approvals in the approver’s app before trusting it. The default ceiling is read, service, config, packages, network, containers and users: it excludes delete, power, access and shell.
What the gateway checks on every change#
A change runs under an approval only if all of these pass, in order:
- The machine is named in the approval.
- The machine is in change mode.
- It is not a delete or power action on a production machine.
- The approval doesn’t deny this kind of action.
- The gateway’s ceiling allows it.
- The approval allows it.
- The approval hasn’t expired.
What happens when …#
A gateway runs on its own and reaches a change#
Nobody is there to approve, so Ysra asks for a signed approval: “I need your signed approval to go on: … Sign it in the Ysra desktop app.” A card reads Approve changes on machines: kinds · until date. In the desktop app choose Approve with this computer’s key; elsewhere the card says Sign it in the Ysra desktop app, which holds your approval key. Once signed, the work goes on.
Ysra can ask for service, config, packages, network, containers and users — never delete, power, access or shell. Its request lasts 1 hour unless it asks for longer, at most 1 day.
Nobody signs (approval ignored)#
Nothing changes. The thread waits for you; a request Ysra made lapses at its end time and counts as expired. A single change card that nobody answers counts as declined. A scheduled automatic run without a valid approval only does its dry run.
The machine or gateway is offline#
| Where | What happens |
|---|---|
| A machine in an automatic run | It ends Not answering; the others carry on |
| The gateway, for a scheduled run | The run doesn’t start: “Nightly camera check” was due but didn’t run: The gateway isn’t connected right now. I’ll try again at its next time. |
| The gateway, for a thread | “gateway isn’t connected right now. Run ysra serve there.” |
An approval is withdrawn#
Withdraw it in the desktop app, or with /approvals in the terminal. Runs
stop using it from their next change, and the thread records Withdrawn: … I no
longer use it.
Automatic runs#
An automatic run carries out a runbook on one or more machines without asking at each step, under a signed approval.
| Stage | What happens |
|---|---|
| Dry run, per machine | Starting checks and each step’s check run; nothing changes. A failing machine is Not ready |
| Steps, per machine | Each step, then its check, as in any runbook |
| Across machines | Up to 10 machines at a time |
| Early stop | When at least 3 machines, and at least half of those finished so far, failed at the same step: I stopped early: 3 of 5 machines failed at step 2; I left the rest alone. Succeeded machines count as finished; skipped ones don’t |
Outcomes per machine#
| Outcome | Meaning |
|---|---|
| Done | Every step ran and every check passed |
| Fixed | A check failed, Ysra applied a fix from a source it cites, the check passed, and the rest ran |
| Needs a person | No fix found, the fix didn’t work, or the approval didn’t cover a step. What Ysra found is in the thread |
| Not ready | The dry run didn’t pass; nothing changed |
| Not answering | The gateway couldn’t reach the machine |
| Skipped | The run stopped before reaching it |
When a check fails: investigate and fix#
When a step’s check fails in an automatic run, Ysra investigates that machine only.
| Rule | Value |
|---|---|
| How it looks | Read-only commands; your workspace’s files first |
| When it applies a fix | Only if a source it read says so: the step’s own If it fails text, or a passage from your documents |
| Approval for the fix | The same as any other change |
| Attempts per machine | 2, then Needs a person |
| Never used | A shell or sudo |
The thread names the source: cam-01 failed at step 1. I looked: … Following “known-issues.md”, I ran … and the check passes now. When it can’t fix it, the line ends … and needs a person. What I found: …. Opening the machine shows Findings and what Ysra ran.
Keep the fix in the runbook#
When the fix came from your documents rather than the runbook, Ysra offers to add it to that step’s If it fails. A card shows If it fails, now and the editable Proposed text, with Add to the runbook or Not now. Adding makes a new version of the runbook: I added it to step 1’s “If it fails” in “Camera check” (version 4).
Schedules#
In the run sheet, set When to On a schedule.
| Field | Options |
|---|---|
| Name | What the schedule is called |
| On these days at | Days from Mon to Sun, and a time |
| Every n minutes | At least 15 minutes, at most a month |
| With the approval | For an automatic schedule: which signed approval it runs under |
Times are your computer’s; the schedule is kept in UTC. Without a signed approval, a schedule is a dry run. Save the schedule lists it under Schedules with dry run or with your approval, how often, and Next: or Paused.
| Button | What it does |
|---|---|
| Pause / Resume | Stops and restarts the schedule |
| Run now | Starts a run at once; results arrive in the thread |
| Delete | Removes the schedule, after Delete it |
Limits#
| Limit | Value |
|---|---|
| Approval lifetime | 5 minutes to 90 days |
| An approval Ysra asks for | 1 hour by default, at most 1 day |
| Machines worked on at once | 10 |
| Fix attempts per machine per run | 2 |
| Shortest schedule interval | 15 minutes |
Related#
- How machines work — approving one change at a time.
- Runbooks — the plan, the dry run, and step-then-check.
- Machines and gateways — the gateway that checks approvals.