Set Up Background Autoupdating

This guide shows you how to configure Swamp to check for and install updates automatically in the background. swamp update also syncs bundled skills for enrolled tools — it only updates skill directories that already exist on disk, so tools you have not set up are unaffected.

Prerequisites

Swamp installed and on your PATH
Signed in with swamp auth login if you use swamp config set — swamp update runs without an account, but swamp config needs one

Root-owned binaries

If your Swamp binary is owned by root (e.g., installed to /usr/local/bin by an administrator), prefix all autoupdate commands with sudo:

$ sudo swamp update --setup-auto

All management commands also require sudo when a root-owned binary is detected:

$ sudo swamp update --setup-auto status
$ sudo swamp update --setup-auto disable
$ sudo swamp config set update.cadence weekly

If you run a management command without sudo, Swamp prints an error explaining that sudo is required.

sudo swamp config set runs as root and reads root's config directory, so root needs its own credential: run sudo swamp auth login first, or use sudo swamp update --setup-auto instead, which needs no account.

If you previously had a user-level scheduler installed, the system-level setup removes it automatically.

macOS

The system-level scheduler installs to /Library/LaunchDaemons/club.swamp.autoupdate.plist and logs to /var/log/swamp/ instead of ~/Library/Logs/swamp/.

Linux

The system-level scheduler installs to /etc/systemd/system/ (systemd timer) or the root crontab via sudo crontab (on systems without systemd). Logs write to /var/log/swamp/ instead of ~/.swamp/log/.

For background on why system-level and user-level schedulers exist and how switching between them works, see Background Autoupdating.

Enable autoupdate interactively

The interactive setup wizard prompts you to choose a cadence and installs the platform-native scheduler in one step:

$ swamp update --setup-auto

The wizard asks whether to check daily or weekly, then installs the scheduler and confirms:

? How often should swamp check for updates? (daily / weekly)
> daily
Autoupdate enabled and scheduler installed

Enable autoupdate non-interactively

For scripted or headless setups, use swamp config set directly:

$ swamp config set update.auto enabled

config·set: Autoupdate enabled and scheduler installed

Choose a cadence

To change the update cadence from the default (daily) to weekly:

$ swamp config set update.cadence weekly

config·set: Cadence updated to "weekly" and scheduler reinstalled

To switch back:

$ swamp config set update.cadence daily

config·set: Cadence updated to "daily"

Check autoupdate status

$ swamp update --setup-auto status

When enabled:

update: Autoupdate: enabled
update: Cadence: "weekly"
update: Scheduler installed: true
update: Last check: "2026-05-07T22:40:18.898Z" ("up_to_date")

When disabled:

update: Autoupdate is disabled. Run `swamp update --setup-auto` to enable.

Disable autoupdate

$ swamp update --setup-auto disable

update: Autoupdate disabled and scheduler removed

You can also disable via swamp config set:

$ swamp config set update.auto disabled

config·set: Autoupdate disabled and scheduler removed

View the autoupdate log

To see recent autoupdate activity:

$ cat ~/.swamp/log/autoupdate.log

You will see output like:

{"timestamp":"2026-05-07T18:27:00.474Z","versionBefore":"20260206.200442.0-sha.","versionAfter":"20260507.175426.0-sha.618a0fec","outcome":"updated"}
{"timestamp":"2026-05-07T22:05:39.415Z","versionBefore":"20260507.214509.0-sha.e2ba2941","versionAfter":null,"outcome":"up_to_date"}

Troubleshoot autoupdate

If autoupdate is not working, run swamp doctor install to diagnose the problem:

$ swamp doctor install

If the output shows UNHEALTHY, check the reported fields:

Binary owned by root — run sudo swamp update --setup-auto to set up autoupdate as a system-level scheduler (see Root-owned binaries above). Alternatively, change ownership to your user:
```
$ sudo chown $(whoami) $(which swamp)
```
Last check shows error — the Last error line describes what failed. Common causes are permission issues and network errors.
Autoupdate disabled — re-enable with swamp update --setup-auto (see above).
Autoupdate has stopped checking for updates, a failed last run, or macOS is refusing to start the autoupdate job — re-register the scheduler with swamp update --setup-auto. Use sudo swamp update --setup-auto for a LaunchDaemon, a system systemd timer or a root cron job.

On macOS, Swamp re-registers the autoupdate job after every update, on the next swamp command after a background update, because launchd refuses to start a replaced binary until the job is registered again. Root re-registers a LaunchDaemon. A failed re-registration is retried once a day.

When autoupdate is enabled and has stopped checking, any swamp command prints a warning at most once a day:

⚠ Background autoupdate has not checked for updates in N days (since <timestamp>).
  Run `swamp doctor install` to see why.

Refer to the Doctor reference for the full output field descriptions.