BACKGROUND AUTOUPDATING

Swamp can update itself in the background without any terminal open. The mechanism is deliberately conservative: opt-in only, platform-native, and logged. This page explains the design choices behind that approach and how the pieces fit together.

Why platform-native scheduling

Background updates need to survive terminal closures, shell exits, and system restarts. A daemon or long-running process could do this, but it would need its own lifecycle management — PID files, crash recovery, startup ordering. That is a lot of machinery for a task that runs once a day.

Instead, swamp delegates scheduling to the operating system. On macOS, it installs a launchd user agent. On Linux, it installs a systemd user timer and service unit. Both are well-understood, battle-tested schedulers that the operating system already manages. They start on login, survive terminal closures, and handle missed-schedule catch-up automatically.

The tradeoff is platform coupling. A cron job would be more portable, but cron has weaker guarantees around missed runs and provides no built-in logging. The platform-native approach gives better reliability at the cost of two code paths instead of one.

The update lifecycle

When the scheduler fires, it runs swamp update --background. This flag tells swamp to run silently — no terminal output, no interactive prompts. The process checks for a newer version, installs it if available, and appends a single JSON line to ~/.swamp/log/autoupdate.log.

Each log entry records three things: the version before the check, the version after (if an update was installed), and the outcome (updated or up_to_date). This makes it straightforward to audit when updates happened and what changed.

If the check fails — network timeout, DNS resolution error, corrupted download — the process exits without modifying the installed binary. The next scheduled run tries again. There is no retry loop or backoff; the scheduler's cadence is the retry interval.

Opt-in by design

Autoupdating is never enabled automatically. A fresh swamp install does not register any scheduler. The user must explicitly opt in, either interactively with swamp update --setup-auto or programmatically with swamp config set update.auto enabled.

The reason is predictability. In production environments, CI pipelines, and Docker containers, an unexpected binary change mid-run could break a workflow or produce inconsistent results. Making autoupdate opt-in ensures that environments where version stability matters are never surprised.

This also means swamp update --setup-auto is safe to recommend broadly. It only affects the machine it runs on, only for the current user (launchd user agent, systemd user timer — not system-wide), and only after explicit consent.

Cadence and the scheduler

Two cadences are supported: daily and weekly. The choice is stored in ~/.swamp/preferences.yaml under the update.cadence key. When the cadence changes, the platform scheduler is reinstalled with the new interval — there is no way to change the cadence without touching the scheduler, because the cadence is a scheduler configuration.

Daily is the default. For most users, checking once a day is frequent enough to stay current without being noticeable. Weekly is available for environments where even a daily check feels too aggressive, or where bandwidth and network access are constrained.

CI and non-interactive environments

Autoupdating has no effect in environments where it was never enabled. A Docker image built from curl -fsSL https://swamp.club/install.sh | sh starts with autoupdate disabled. A CI job that installs swamp from a pinned URL gets exactly that version. There is no silent opt-in, no telemetry-based enrollment, and no first-run prompt.

If you need version pinning in CI, install a specific version and do not enable autoupdate. If you want CI to always use the latest version, run swamp update as an explicit step in your pipeline rather than relying on background scheduling — the scheduler assumes a persistent user session, which most CI runners do not provide.

Where the pieces live

On macOS, the launchd plist is written to ~/Library/LaunchAgents/. On Linux, the timer and service units are written to ~/.config/systemd/user/. The configuration lives in ~/.swamp/preferences.yaml (update.auto and update.cadence keys). The log at ~/.swamp/log/autoupdate.log is append-only and never rotated by swamp itself.