Stackie

Alpha Preview

Updates

Updates

Stackie updates itself automatically in the background without interrupting your running sandboxes.

How updates work

  1. Background check — stackied checks for a new version once per hour (configurable). The check is silent and does not affect running sandboxes.
  2. Download — When a new version is available, the package is downloaded and checksummed in ~/.stackie/updates/.
  3. Apply on exit — The update is applied the next time you quit Stackie through the tray menu or stackie stop. A sidecar process (stackie-updater) extracts the new binaries after the daemon exits.
  4. Health check — After extracting, the sidecar launches the new daemon and waits up to 5 seconds for it to accept TCP connections. If the health check passes, the update is committed and the backup is removed.

Rollback on failure

If the update fails — either during extraction or because the new daemon does not pass the health check — Stackie automatically rolls back to the previous version:

  1. The sidecar kills the new daemon (if it was started).
  2. The previous binaries are copied from ~/.stackie/backup/ back to ~/.stackie/bin/.
  3. The old daemon is relaunched.
  4. The error is logged to ~/.stackie/logs/updater.log.

No user action is required for a rollback.

Startup self-healing

If the sidecar is killed mid-update (for example, due to a power loss), the backup directory will still exist but the .update-ok marker will be absent. The next time stackied starts, it detects this state and self-heals:

  • If ~/.stackie/backup/ exists and ~/.stackie/bin/.update-ok is absent, the previous binaries are restored from backup.
  • If ~/.stackie/backup/ exists and .update-ok is present, the backup is treated as stale and removed.

Manual update

To check for and apply an update immediately:

stackie update

To install a specific version:

stackie update --version 0.9.0

Configuration

Update behaviour is controlled in ~/.stackie/stackie.yaml under the updates: key:

updates:
  channel: stable          # stable | canary | edge
  auto_update: true        # apply update automatically on next quit
  check_interval_secs: 3600  # how often to check (default: 1 hour)

Set auto_update: false to disable automatic application of updates. You will still be notified via the tray icon and can apply updates manually.

Troubleshooting

My install is broken after a failed update

The startup self-healing mechanism should automatically restore the previous version on next launch. If stackied refuses to start, run:

stackie update

This downloads and installs the latest release fresh, regardless of the current state of ~/.stackie/bin/.

I switched channels and now stackie won’t start

If you switched to an older channel (for example, from edge to stable), the database schema version may be ahead of what the installed binary supports. You will see an error like:

Database schema version N is ahead of the maximum supported version M.
Run a newer binary or delete ~/.stackie/stackied.db to reset.

To recover, delete the database (your stack definitions are unaffected):

rm ~/.stackie/stackied.db

Nuclear reset

If nothing else works, a full reset clears all Stackie state:

rm -rf ~/.stackie

Re-run the installer afterwards:

curl -fsSL https://stackie.dev/install.sh | sh

Your stack files (typically stackie-stack.yml) live in your project directories and are not affected.

Note: A full reset will require you to re-download package caches and re-authorise any authenticated services (e.g., private npm registries).

See also