elizaos--eliza/packages/deploy/systemd

Eliza bare-metal systemd bundle

Run Eliza directly on a Linux host as systemd user services — no Docker, no container-in-container. Best for one bot on one VPS (or a local Linux box) against a personal Claude Max subscription, where you want PTY subagents and OAuth to use the same ~/.claude credentials the claude CLI created.

Full guide: /deployment-bare-metal. For Docker / multi-tenant / API-key-first deployments, use the Deployment Guide instead.

Layout

packages/deploy/systemd/
  install.sh                  idempotent installer (user services)
  smoke-test.sh               static unit/script contract check (no install)
  eliza.env.example           env template -> ~/.config/eliza/env on first install
  units/
    eliza.service             the bot: Restart=always, OAuth refresh before launch
    eliza-refresh.{service,timer}   roll the OAuth token every 6h
    eliza-probe.{service,timer}     health probe every 5 min (restart on failure)
  bin/
    eliza-refresh-oauth.sh    refresh only when the token is near expiry; never runs a model
    eliza-health-probe.sh     /api/health + agentState + auth-log check; restart-on-failure

Prerequisites

• Linux host with systemd (user sessions + linger). Any modern distro.
• bun on the installing user's PATH.
• claude CLI installed and logged in once (claude auth login).
• Run as your normal user — not root.

Install

git clone https://github.com/elizaOS/eliza.git
cd eliza
./packages/deploy/systemd/install.sh   # or: ./packages/deploy/systemd/install.sh /opt/eliza

The installer substitutes the resolved workdir, your bun path, and the log path into the unit templates, writes them to ~/.config/systemd/user/, copies the helper scripts to ~/bin/, seeds ~/.config/eliza/env on first run, enables linger, and starts the service + timers.

Uninstall

systemctl --user disable --now eliza.service eliza-refresh.timer eliza-probe.timer
rm -f ~/.config/systemd/user/eliza{,-refresh,-probe}.{service,timer}
rm -f ~/bin/eliza-refresh-oauth.sh ~/bin/eliza-health-probe.sh
systemctl --user daemon-reload
loginctl disable-linger "$USER"   # optional

Smoke Test

./packages/deploy/systemd/smoke-test.sh

The smoke test renders every unit template into a temporary directory, verifies that all installer substitutions are resolved, syntax-checks the helper scripts and installer, and runs systemd-analyze verify when available. It does not install units, enable linger, start services, or require Claude credentials.