BEAM·v0.1.1·MACOS · LINUX·SHA-256 VERIFIED
DOCS/Advanced/Self-update

Self-update

Beam ships with `beam update` — a SHA-256-verified self-update from the public `polybase/payy` GitHub Release feed.

See also: the update command reference for the user-facing flags.

How it works

  1. beam update queries the public polybase/payy GitHub Releases feed.
  2. It selects the newest stable release that includes the current platform asset with a valid sha256: digest.
  3. The asset is downloaded.
  4. The downloaded binary is verified against the release's SHA-256 digest.
  5. Only if the digest matches does Beam swap the running executable in place.

Any digest mismatch aborts the update. There is no fallback that runs an unverified binary.

Why it's a separate code path

beam update bypasses the normal Beam state bootstrap. That means:

  • It still works when config.json, chains.json, or wallets.json need repair.
  • It is the only command that requires the live GitHub check to finish before proceeding.
  • Other commands rely on a cached check in ~/.beam/update-status.json, refreshed asynchronously at most once every 24 hours.

Update notice

In default output mode, Beam prints an update warning when the cached status indicates a newer release is available. JSON/YAML/compact/quiet output modes suppress the notice so scripted runs stay clean.

The cache lives at ~/.beam/update-status.json.

Release naming

  • Tags are beam-v<version>.
  • Assets shipped per release:
    • beam-x86_64-unknown-linux-gnu
    • beam-x86_64-apple-darwin
    • beam-aarch64-apple-darwin

The installer and beam update only consider non-draft, non-prerelease beam-v<version> releases from polybase/payy, and only select a release when it contains the current platform asset with a valid sha256: digest. Other release trains in the same repo don't affect Beam downloads.

Release control

Releases are published from polybase/payy via .github/workflows/beam.release.yml. The workflow builds the platform binaries and publishes the beam-v<version> GitHub Release assets that the installer and beam update consume.

Each beam-v<version> tag publishes once — reruns skip rather than overwriting, so the maintainer team cuts a new version before re-releasing.

Version bumps follow conventional-commit semantics: feat → minor, breaking change → major, anything else → patch. Maintainers can also pick an explicit version when triggering the release manually.

◂ PreviousREPL