Always-on agents · Set it up anywhere

Running an always-on agent on Alpine Linux

Alpine is the distribution under more containers than any other, and the only one in this series without systemd. The agent still needs a user, a supervisor, a schedule and a place for its secrets; Alpine spells all four differently. Here is what changes, with the real output from a fresh 3.22 container.

In short

On Alpine the agent runs as an OpenRC service: a script in /etc/init.d with supervisor set to supervise-daemon, which restarts the process when it dies, enabled with rc-update. Python packages need musllinux wheels, and a package without one builds from source. Busybox crond handles the schedule but cannot catch up on missed runs. Pick Alpine for a tiny, disposable host.

Part of the Always-on agents series, post 32 of 33.

I came to Alpine the way most people do: it was already there, underneath a container image, small and quiet. Running an always-on agent on it directly is a different proposition. There is no systemd, so most of the Linux advice in this series needs translating, and the C library is musl rather than glibc, which is the thing that will surprise you on the first pip install. This page is only the translation. The ten steps and the reasons behind them are in the Linux core page.

What I tested, exactly

A fresh alpine:3.22 container on my Mac, which is an arm64 machine, so this is Alpine 3.22.6 on aarch64 with musl. OpenRC does run inside a container if you tell it the boot has already happened, which is a trick I note below and which no real Alpine host needs. What a container cannot show you is a real boot, networking as OpenRC sees it, or cgroup limits, and the output below includes the exact warning that proves it. Everything else here ran.

The Alpine sequence

Seven steps, in the order I ran them in the container; the rest of this page is the detail behind each.

  1. Install the runtime and OpenRC. apk add --no-cache python3 openrc; there is no systemd to install.
  2. Create the agent's user and venv. busybox adduser flags, and a venv under /srv/agent that the user owns.
  3. Write the OpenRC script. /etc/init.d/agent with supervisor=supervise-daemon, command_user and a respawn delay.
  4. Enable and start it. rc-update add agent default, then rc-service agent start.
  5. Prove the respawn. Kill the agent process, not the supervisor, and watch a new pid appear.
  6. Check every wheel before production. pip download --only-binary=:all: for the whole requirements file; fix what fails now.
  7. Schedule the rest with busybox crond. And put catch-up logic in the job itself, because crond has none.

Packages and the agent's user

Terminal# a fresh Alpine 3.22 container, as root
apk add --no-cache python3 openrc
python3 --version        # Python 3.12.15
apk info openrc          # openrc-0.62.6-r0
ldd --version            # musl libc (aarch64)

# the agent's own user and a venv it owns
addgroup -S agent
adduser -S -D -H -h /srv/agent -s /sbin/nologin -G agent agent
mkdir -p /srv/agent && chown agent:agent /srv/agent
python3 -m venv /srv/agent/venv

Two Alpine spellings to notice. adduser is busybox's, so the flags differ from Debian's: -S for a system user, -D for no password, -H to skip creating the home, -s for the shell. And apk add --no-cache is the habit worth keeping even on a real host, because it leaves no index behind to go stale.

The service: OpenRC and supervise-daemon

OpenRC's service scripts are shell, with a dedicated interpreter. The OpenRC project's own guide is clear that the shebang must be /sbin/openrc-run, not /bin/sh, or dependency handling breaks. The one line that does the work of systemd's Restart=always is supervisor=supervise-daemon, which makes OpenRC keep the process in the foreground under a supervisor and respawn it when it dies. The guide also says to keep the default start, stop and status functions, because custom ones switch the supervision off.

/etc/init.d/agent#!/sbin/openrc-run
name="agent"
description="Always-on agent (heartbeat loop)"
supervisor=supervise-daemon
command="/srv/agent/venv/bin/python3"
command_args="/srv/agent/agent.py"
command_user="agent:agent"
directory="/srv/agent"
respawn_delay=5
respawn_max=0
output_log="/var/log/agent/stdout.log"
error_log="/var/log/agent/stderr.log"

depend() {
    need net
    after firewall
}

start_pre() {
    checkpath --directory --owner agent:agent --mode 0750 /var/log/agent
}

respawn_delay is the five seconds I use everywhere, and respawn_max=0 means unlimited respawns, which the guide documents; the default is ten. The directory, output_log and error_log variables are supervise-daemon's, not systemd's, and they are the only logging you get, because there is no journal. command_user runs the process as the agent's user, which the guide recommends when the program cannot drop privileges itself. One warning from the same guide that I agree with: do not use checkpath to hand an unprivileged user a PID directory. I use it for the log directory only.

Terminalchmod +x /etc/init.d/agent
rc-update add agent default
#  * service agent added to runlevel default
rc-service agent start
#  * /var/log/agent: creating directory
#  * /var/log/agent: correcting owner
#  * Starting agent ... [ ok ]
rc-service agent status
#  * status: started
rc-status
#  agent    [  started 00:01:07 (0) ]

Inside a container, rc-service refuses to start anything until a softlevel file exists, because OpenRC believes the system is still booting; mkdir -p /run/openrc and touch /run/openrc/softlevel clears that. The container also printed a warning I want to show rather than hide: mkdir can't create /sys/fs/cgroup/openrc.agent, read-only file system. That is the container's cgroup tree, which OpenRC would use to group the service's processes on a real host. It does not stop the service, and you will not see it on real Alpine.

Does it come back when it dies?

This is the test that matters for an always-on host, and I ran it twice, because the first time I got it wrong in an instructive way. The process listing shows what OpenRC really launched: a supervise-daemon with my delay and unlimited respawns, plus a respawn period of 1800 seconds that I never set, holding the agent as its child.

Terminal# what OpenRC actually started (ps -o pid,user,args, trimmed)
158 root   supervise-daemon agent --start --chdir /srv/agent --stdout /var/log/agent/stdout.log
             --stderr /var/log/agent/stderr.log --respawn-delay 5 --respawn-max 0
             --respawn-period 1800 --user agent agent /srv/agent/venv/bin/python3 --
160 agent  /srv/agent/venv/bin/python3 /srv/agent/agent.py

# a second run: kill the agent, not the supervisor, and watch pgrep
cat /var/run/supervise-agent.pid           # 146, the supervisor
pgrep -f "python3 /srv/agent/agent.py"     # 148, the agent
tail -1 /var/log/agent/heartbeat.log       # 2026-10-21T14:31:24 alive pid=148
kill -9 148
# polled pgrep once a second:
#   agent pid after: 152 (after 1s)

Killed with -9, the agent was back under a new pid within a second, sooner than the five-second delay I had configured; I report what I saw rather than what the variable name promised. In the first run I had killed the supervisor itself by mistake. The agent kept running as an orphan and rc-service agent status still said started, which is worth knowing: status reports the supervisor's view, and once the supervisor is gone nothing will respawn the agent when it finally dies.

musl and the wheel that is not there

This is the part I would check before anything else. Python packages with compiled parts ship as wheels built against glibc, tagged manylinux. Alpine uses musl, and PEP 656 says it plainly: musl is a different libc implementation from glibc, and therefore cannot use the existing manylinux platform tags. Popular packages now also publish musllinux wheels, and pip picks them up without you noticing. A package without one falls back to building from source, which fails until you install the compiler and headers.

Terminal# ask pip for a wheel only, no source builds allowed
/srv/agent/venv/bin/pip download --no-deps --only-binary=:all: -d /tmp/wh pydantic-core
#  pydantic_core-2.50.1-cp312-cp312-musllinux_1_1_aarch64.whl
/srv/agent/venv/bin/pip download --no-deps --only-binary=:all: -d /tmp/wh2 psycopg2-binary
#  psycopg2_binary-2.9.13-cp312-cp312-musllinux_1_2_aarch64.whl

# a package that ships glibc wheels but no musllinux wheel fails here, not at 3am
/srv/agent/venv/bin/pip download --no-deps --only-binary=:all: -d /tmp/w torch
#  ERROR: Could not find a version that satisfies the requirement torch (from versions: none)

My rule for an agent host on Alpine: before you commit, run pip download with --only-binary=:all: for everything in your requirements. If it all resolves, you are fine. If one package has no musllinux wheel, decide whether to apk add build-base and the headers it needs, or to pick a different package, before the machine is in production and the build breaks on an update.

Schedules: busybox crond, and its limit

There is no systemd timer, so the daily digest runs from cron. Alpine's cron is busybox crond, which reads per-user crontabs from /etc/crontabs and is started as an OpenRC service itself.

Terminal# busybox crond reads /etc/crontabs/<user>; one line per job, no @reboot persistence
echo '0 7 * * * /srv/agent/venv/bin/python3 /srv/agent/digest.py' > /etc/crontabs/agent
rc-update add crond default && rc-service crond start

The limit matters for an always-on agent: busybox crond has nothing like systemd's Persistent. If the host was off at 07:00, the digest does not run at 07:01 when it comes back; it runs tomorrow. The catch-up rule from the first post has to live in the script instead: have the digest check what it last did and do everything since. That is how my own publisher works, and on Alpine it is not optional.

When Alpine is the right call

Where I would use it, and where I would not:

  • A tiny, disposable host. A few megabytes of base system, a fast rebuild, nothing you will miss when you throw it away. Good for an agent that is itself a container.
  • Pure-Python agents, or ones with popular dependencies. The musl question is a non-issue when every wheel exists.
  • Not for local models. The inference stacks in the local models post assume glibc; build them on musl only if you enjoy it.
  • Not for a first always-on host. If you are new to this, Debian gives you systemd, a journal and timers that catch up. Come to Alpine when small is the point.

The next distribution guide, NixOS, is Alpine's opposite in almost every way: large, declarative, with a systemd it wraps in a language. Between the two of them you have the full range of what an always-on host can be.

Sources

  1. OpenRC, Service script guide (accessed October 20, 2026)
  2. OpenRC, supervise-daemon guide (accessed October 20, 2026)
  3. Python Enhancement Proposals, PEP 656: Platform tag for Linux distributions using musl (accessed October 20, 2026)
  4. Alpine Linux, Alpine Linux 3.22 release (apk packages: python3, openrc) (accessed October 20, 2026)

Written by Lera Leonteva. Commands and output above are from a fresh alpine:3.22 container on an arm64 Mac on the access date.

Frequently asked questions

How do I keep a process running on Alpine without systemd?

Write an OpenRC service script in /etc/init.d with supervisor=supervise-daemon, command and command_user set, then rc-update add it to the default runlevel. supervise-daemon restarts the process when it exits, with respawn_delay and respawn_max controlling how often.

Why does pip install fail on Alpine when it works on Ubuntu?

Alpine uses musl rather than glibc, so wheels tagged manylinux do not apply. pip needs a musllinux wheel for the package; when there is none, it builds from source and needs apk add build-base plus the package's headers.

Does Alpine's cron catch up on a missed run?

No. busybox crond has no equivalent of systemd's Persistent=true. If the host was off at the scheduled time, the job waits for the next occurrence. Put the catch-up logic in the job itself.

Can I run OpenRC services inside a Docker container?

For testing, yes: create /run/openrc/softlevel so OpenRC believes the boot is complete, then rc-service start works. Expect a read-only cgroup warning, which is the container's, not Alpine's, and do not call rc-service stop: with no real init it waited on the supervisor's pidfile and never returned for me. Kill the supervisor by pid instead. For production, run the agent as the container's main process and let the container runtime supervise it.

Is Alpine a good host for a local language model?

Not usually. The common inference stacks assume glibc and publish binaries for it. Run the model on a glibc distribution or a Mac and point the Alpine-hosted agent at it over the network.

Lera Leonteva
Lera Leonteva
CEO & Founder, Leo AI

Lera Leonteva is the founder and CEO of Leo AI, where she works on turning long-form footage into short-form video that earns attention on its own merits. She writes Video Scaling Strategies, taking one piece of content that worked and one that did not, and using what the market is doing to explain the gap.

The always-on agent I run for social video

Leo watches what your audience is responding to, picks a clip from footage you already have, edits it and books it on the calendar. Every hour, without being asked. It is the agent this whole series grew out of.

Keep going with the series

Every post in the Always-on agents series is on one page, newest first. If you would rather see the agent I run for social video, here it is.