Security Updates Without the 3 a.m. Surprise: Unattended Upgrades for Agent Boxes

Most home agent boxes end up in one of two bad places with updates.

The first is the box nobody patches. It was set up in a weekend, it works, and nobody wants to touch it. Six months later it is running an SSH server, a web listener, and a browser with a long list of known security fixes it never received. It holds your API keys, your email access, and sometimes payment tokens. That is a lot to leave on an unpatched machine that is online all day.

The second is the box that patches itself whenever it feels like it. Updates start at a random hour, a package restarts a service in the middle of a job, a kernel update waits for a reboot nobody does, or the box reboots itself at 7:55 a.m., right before the morning brief is supposed to go out.

The fix is not to pick one of these. It is to let the box install security updates on its own, on a schedule you choose, with a short list of things it must not touch, and a clear signal when it needs a reboot. On Debian, Ubuntu, and Raspberry Pi OS, the tool for that is unattended-upgrades. This post walks through setting it up for an agent box in about 20 minutes.

What automatic updates do and do not cover

Be clear about the scope first, because this is where people get a false sense of safety.

unattended-upgrades installs updates for packages that came from apt. That covers the operating system, OpenSSH, the kernel, system libraries like OpenSSL, and anything else you installed with apt install.

It does not cover:

  • Node, Python, or other runtimes you installed some other way, such as from a version manager or a downloaded binary.
  • npm and pip packages inside your agent project.
  • Docker images. A container keeps whatever was baked into its image until you pull a new one and recreate it.
  • The agent runtime itself, if you installed it from a release download or a git checkout.

Those still need their own update routine. For the agent runtime, the release stability checklist covers how to upgrade on purpose instead of on impulse. Automatic OS updates are the floor, not the whole house.

Step 1: Install it and turn it on

Over SSH:

sudo apt update
sudo apt install unattended-upgrades apt-listchanges
sudo dpkg-reconfigure -plow unattended-upgrades

Answer yes when it asks whether to download and install stable updates automatically. That writes a small file at /etc/apt/apt.conf.d/20auto-upgrades. Open it and make sure it contains these two lines:

APT::Periodic::Update-Package-Lists "1";
APT::Periodic::Unattended-Upgrade "1";

The first refreshes the package lists every day. The second lets the upgrade step actually run.

Step 2: Make sure it only installs what you want

The main settings live in /etc/apt/apt.conf.d/50unattended-upgrades. Open it with sudo nano and look for the section called Unattended-Upgrade::Origins-Pattern. Those lines decide which repositories it is allowed to install from.

The defaults are sensible: security updates for your release, and often regular stable updates too. For an agent box, a security-only setup is a reasonable starting point. You get the fixes that matter without pulling in every feature update. If your file has a line for the regular updates channel that you do not want, comment it out with // at the start.

Then add anything that must never be updated without you watching. That goes in Unattended-Upgrade::Package-Blacklist:

Unattended-Upgrade::Package-Blacklist {
    "docker-ce";
    "docker-ce-cli";
    "containerd.io";
};

Docker is a common entry because an update restarts the Docker service, which restarts every container on the box at the same time. If your agent or its webhook listener runs in a container, that restart can land in the middle of a job. Keep this list short. Every package on it is one you now have to update by hand, so only add things whose restart would actually hurt.

For a single package you want frozen for a while, apt-mark does the same job from the command line:

sudo apt-mark hold docker-ce
apt-mark showhold

Write down anything you hold, and why, in the same place you keep your other box notes. A hold you forgot about becomes the unpatched package nobody remembers.

Step 3: Decide when it runs

By default, two systemd timers drive the process. One refreshes package lists and downloads updates, and the other installs them. Both run at a randomized time, which is exactly what you do not want on a box with a morning schedule.

See when they are set to fire:

systemctl list-timers 'apt-daily*'

Then move the install step to a quiet window, well away from your jobs:

sudo systemctl edit apt-daily-upgrade.timer

Add this in the editor that opens:

[Timer]
OnCalendar=
OnCalendar=*-*-* 03:30
RandomizedDelaySec=0

The empty OnCalendar= line clears the default before you set your own. Pick a time with nothing important running before or after it. If your morning brief or daily post runs at 7:30, an install window at 3:30 leaves plenty of room for anything that goes wrong to show up before it matters.

Check the time zone the box thinks it is in before you trust that number. A box set to UTC will run “3:30” at a very different local hour. The clock check guide covers how to confirm the clock and time zone are right.

Step 4: Handle reboots on purpose

Some updates, especially the kernel and core libraries, do not fully take effect until the box restarts. When that happens, the system creates a file:

ls /var/run/reboot-required
cat /var/run/reboot-required.pkgs

If the file exists, a reboot is due, and the second file lists which packages asked for it.

You have two choices.

Let it reboot itself at a fixed time. In 50unattended-upgrades:

Unattended-Upgrade::Automatic-Reboot "true";
Unattended-Upgrade::Automatic-Reboot-Time "04:00";

This only reboots when a reboot is actually required, and only at that time. It is a good choice if you have already proven the box comes back cleanly on its own. If you have not, run the reboot test first. An automatic reboot onto a box whose agent does not start on boot is worse than no reboot at all.

Leave it off and get told. Keep Automatic-Reboot set to "false" and add one line to your daily heartbeat or morning report that checks for the file:

test -f /var/run/reboot-required && echo "Reboot pending: $(tr '\n' ' ' < /var/run/reboot-required.pkgs)"

Then reboot by hand when it suits you. This is the better choice while you are still learning how the box behaves.

What you should not do is leave it off and never look. A reboot that has been pending for three months means the kernel fix you thought you had is not actually running.

Step 5: Prove it works before you trust it

Do a dry run. It shows exactly what would be installed without changing anything:

sudo unattended-upgrade --dry-run --debug

Read the output. You want to see it pick up the right repositories, skip anything on your blacklist, and either find updates to install or report that there is nothing to do. If it says no packages match your origins, your Origins-Pattern lines do not match where your packages actually come from, and nothing will ever be installed.

After the first real run, check the logs:

sudo tail -n 50 /var/log/unattended-upgrades/unattended-upgrades.log
grep -A3 "Start-Date" /var/log/apt/history.log | tail -n 20

The first log shows what the tool decided. The second shows what apt actually installed and when. If you see installs at the time you set in step 3, the schedule works.

Step 6: Watch the morning after

The first few times updates install, look at the jobs that ran afterward. Did the morning brief go out? Did the webhook listener stay up? Did any service restart count jump?

systemctl show -p NRestarts --value your-agent.service

A package update can restart a service that your agent depends on, such as a database or a reverse proxy. Most of the time, the service comes right back and nobody notices. If something did not come back, you want to find out the morning it happened, not a week later. The stalled automation alarm post covers how to get alerted from outside the box when a job stops producing output.

Before turning any of this on, make sure you have a backup you have actually restored at least once. Updates almost never break a box badly, but when they do, the restore drill is what turns a bad morning into a 30-minute fix.

The short version

  1. Install unattended-upgrades and confirm both lines in 20auto-upgrades are set to "1".
  2. Limit it to security updates and blacklist the few packages whose restart would hurt, like Docker.
  3. Move apt-daily-upgrade.timer to a fixed quiet hour and remove the random delay.
  4. Either allow automatic reboots at a fixed time after passing a reboot test, or report /var/run/reboot-required in your daily heartbeat.
  5. Run unattended-upgrade --dry-run --debug, then check the logs after the first real run.
  6. Remember that npm, pip, Docker images, and the agent runtime still need their own update plan.

None of this makes the box exciting. It makes it boring in the right way: patched every night at 3:30, rebooted when you decide, and still working when the morning jobs start.

Have your agent report on its own patches

If you want your agent to check this for you every morning, start with MarketMai’s free AI prompt pack and adapt one into a “summarize last night’s package installs, flag any pending reboot, and list held packages older than 30 days” task. When you are ready to run more of your operations on agents, the OpenClaw Agent Ops Toolkit gives you production configs and runbooks for setup, security hardening, monitoring, and cron, and the MarketMai Ultimate Bundle puts 13 prompt, automation, and agent-operations products in one $49 download.

More from the build log

Suggested

Want the full MarketMai stack?

Get the core MarketMai guides and operator playbooks in one premium bundle for $49.

View Bundle