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

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.

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).

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