Skip to main content

​
Updating

The public installer keeps a checkout as the setup and repair anchor. The active runtime depends on the install profile:
  • Supported Linux Local and VPS Hosting installs normally run a verified prebuilt release artifact.
  • Their CLI and Gateway service resolve the active version through a stable launcher outside the versioned application directory.
  • macOS and explicit --source-install installs run from the source checkout.
  • fased update is the normal update command for both profiles.
  • The Control UI currently reports update status; it does not start the update.
  • Rerun ./install.sh for repair or reinstall behavior.
The update path should not require committing generated files. Native signer artifacts, build outputs, and service state are install artifacts; keep source changes separate from runtime refreshes. fased onboard --install-daemon is setup and service installation. It is not the primary version-update command. For a managed Linux Local or WSL install, updates work from any directory:
Source/developer checkouts should still run from their checkout directory. On a hosted VPS, use the app user through Tailscale:
After hosted onboarding, SSH as app should open directly in /home/app/fased. If it does not, fix the hosted login/shell setup before updating. For a fresh hosted VPS, use the exact fresh Hosting command from the VPS provider root shell. The verified script installs the exact selected release and verifies the tagged Hosting artifacts before privileged Fased installation. Users who require verification before the first script runs can use the expandable advanced procedure in Advanced installer. Run the first Hosting install from the VPS provider’s root shell. That path creates the human app operator, isolated fased-gateway and fased-signer services, private Tailscale access, and the hosted posture. Use the Tailscale hostname and app for normal operation and updates. A successful fresh install does not require --repair-hosting afterward. A manual global npm install is an advanced local/dev or self-managed-host path; it is not the normal VPS Hosting path.

​
CLI update

Use this for the gateway-aware update flow on an existing install. Managed artifact updates require a Gateway restart and health verification; --no-restart is accepted only when no runtime change is needed. Source and manual package-manager profiles retain their existing restart option. By default, fased update uses the stable channel. On a git checkout, stable means the newest stable v* release tag. It does not mean the moving head of main. On managed package installs, npm latest resolves the exact version; the update downloads verified GitHub release layers and does not run a global npm dependency reconciliation. Use this for normal end-user updates:
Use the developer channel only when you intentionally want the latest commits from main:
For development/testing from a source checkout, use the explicit source path:
Privileged VPS Hosting refuses source checkouts. Test development Hosting work on a disposable self-managed machine; do not run /home/app/fased/install.sh with sudo or describe that setup as the maintained Hosting boundary.

​
Native signer artifacts

Fresh dashboard, Gateway, and Fased Network setup do not require fased-signerd. The native signer is only needed after you choose the local signer wallet path. When that path is enabled, Fased downloads the signer asset from the matching versioned GitHub Release and verifies it against fased-signerd-checksums.txt and the release’s GitHub/Sigstore attestation. The release also includes an attested fased-signerd-release.json. Hosting accepts only a production identity whose exact version, commit, and build-input digest match both that manifest and the running signer’s health response; development, missing, or mismatched identities fail closed. Normal Local, WSL, macOS, and Hosting users do not need Go. WSL uses the Linux asset; the Unix-socket signer is not supported by a native Windows Node.js install. Verification failure stops the install instead of falling back to an implicit source build. When a Local install already has a native signer, fased update treats the Gateway and signer as one transaction. It snapshots the current application and signer state, stages the exact version-matched signer read-only, activates the application, and requires exact Gateway and signer health before committing the signer read-write. Before that durable health decision, a failure restores both sides. After the decision, recovery completes forward so a signer database that may have recorded a request is never replaced by an older snapshot. This pairing also applies to tagged macOS and explicit source installs. A source checkout with a configured signer must be clean, resolve to a production release tag, allow the required restart, and pass the same exact health checks. Signer-paired source updates reject an untagged development commit, --no-restart, or an install-mode switch. Interrupted updates recover from the owner-only transaction journal before the Gateway starts. Each tagged release must publish signer assets for Linux and macOS on amd64 and arm64 before wallet setup for that version is considered releasable. A source checkout can still opt into a local build with FASED_BUILD_NATIVE_SIGNER_FROM_SOURCE=1 and Go >= 1.25.7. Existing binaries and alternate trusted release sources remain available through FASED_WALLET_LOCAL_SIGNER_BIN, FASED_LOCAL_SIGNER_VERSION, and FASED_LOCAL_SIGNER_BASE_URL. Existing Local/WSL2 SAT operators that explicitly use large distribution v0 transactions keep FASED_SAT_ENABLE_ALT_V0 and FASED_SAT_PROGRAM_ID from managed config across restart/update. An update does not silently enable the feature or widen signer policy; exact satLookup grants still require owner-policy acknowledgement. Do not commit generated signer binaries to Git, and do not cut a release just to test signer setup.

​
Control UI update status

The browser Control UI shows read-only update state at:
Use the CLI to run the update:
The status card can show the current version, update channel, install source, package or Git state, and whether an update is available. The actual update and restart remain terminal operations.

​
Installer rerun

Rerun ./install.sh only for a Local/source checkout repair or contributor workflow. Current installers refresh a clean checkout first. Supported Linux Local profiles then prefer the verified prebuilt runtime artifact. macOS and explicit --source-install runs refresh dependencies and build. If the installer itself changes, it restarts once and continues with the updated script.
Do not rerun /home/app/fased/install.sh on Hosting, with or without sudo. Use fased update from the app shell for normal Hosting updates. Use the exact tagged, attested --repair-hosting procedure from the VPS provider root console only when the managed updater or root-owned service is broken. Use ./install.sh --no-git-update only when testing local changes.

​
What onboard does versus what update does

fased onboard --install-daemon:
  • configures the runtime
  • installs or refreshes the service
  • writes runtime env such as SAT ids into the installed runtime
fased update:
  • updates to the configured channel; stable is the default end-user channel and resolves to the newest stable release tag
  • uses a verified release artifact for the managed VPS runtime when available
  • uses the same verified artifact for supported Linux Local installs
  • refreshes dependencies and rebuilds for macOS or explicit source installs
  • checks tracked npm plugins after the core update
  • detects the local user service or root-managed VPS Hosting service
  • restarts the correct service and verifies Gateway health
  • restores the previous packaged runtime automatically if post-update health fails
For a healthy supported install, fased update is the complete release update. You should not need to clear npm caches, reinstall dependencies manually, or run a separate Gateway repair command. If the installed packaged version already matches the selected release, fased update returns Already current: <version> without downloading an artifact, changing plugins, or restarting the Gateway. Supported Linux artifacts are layered. A fresh install downloads the application and dependency layers once. Normal updates reuse the dependency layer when its build hash is unchanged and replace only the application layer. When the dependency recipe or lockfile changes, the next update replaces that layer once and later updates reuse it again. The managed launcher and updater are deliberately outside each application version:
fased update resolves the target online without stale npm cache metadata, verifies checksums and archive paths, stages and smoke-tests the candidate, switches current atomically, verifies Gateway identity and plugins, and rolls back automatically on failure. Configuration, credentials, wallets, signer state, mining data, sessions, and memory remain under the state directory and are never part of the release swap.

​
Legacy hosted updater repair

Very old hosted releases may contain an updater that cannot install its own replacement. A typical symptom is an update that reports success while fased --version remains unchanged. Code added in a newer release cannot run inside that already-installed old binary. This is not a normal update and is not a follow-up step after a successful fresh install. If the install is known to predate the external managed updater, or fased update already failed or left the version unchanged, do not repeatedly run the old updater. Go directly to the exact tagged root repair below. The repair must restore root-owned service helpers and the system service. Open the VPS provider’s web/recovery console as root (or use root SSH only when the provider still permits it). Follow the exact manual pre-execution verification procedure, but replace the final invocation of the already-verified standalone installer with:
Do not run this command unless the preceding gh attestation verify step completed successfully for the same exact release. Remove BOOTSTRAP_DIR only after the repair succeeds. Do not run this command from the normal app Tailscale shell, and never run /home/app/fased/install.sh with sudo. The restricted app account has no sudo and no root bootstrap socket. The provider-console bootstrap verifies the exact tagged app bundle attestation before loading any privileged assets. The repair keeps the existing /home/app/fased checkout and persistent /home/app/.fased state. It refreshes the managed runtime, replaces a legacy app-managed user service with the supported root-managed service, restarts the Gateway, and skips onboarding. Wallets, mining state, credentials, sessions, plugins, and configuration are not reset. For Tailscale Serve, repair also keeps the Gateway on loopback, trusts only the loopback proxy ranges, and removes the obsolete allowInsecureAuth compatibility flag. Tailscale HTTPS, shared Gateway auth, and device/session identity remain active. After this one repair, return to the normal command:
This repair is only for VPS Hosting installs with the root-managed service. Local users must not run --repair-hosting. If their historical Local/WSL binary cannot complete fased update, use the Local repair command in the support contract below.

​
One-time pre-v2 Local wallet migration

If fased update reports a pre-v2 Local wallet, it stops before stopping a process or replacing a file. This is intentional: the updater and Gateway must not read an old wallet passphrase. First make an offline backup and record the public address. Run the exact tagged Local repair later on this page if the old CLI lacks the native signer admin path; it leaves legacy wallet material untouched. Put the old passphrase in a separate owner-only file, run fased-signerd admin wallet import-legacy with the wallet’s permanent Agent, Mining, or Vault role, and compare the returned public address with the address recorded before migration. Then finalize the non-secret config/registry conversion:
The native signer reads and consumes the encrypted keystore/passphrase paths. Do not put the passphrase in FASED_WALLET_PASSPHRASE, command arguments, PowerShell, the dashboard, chat, or a skill. WSL2 users run all three Bash blocks in the Ubuntu shell, not PowerShell. Existing signer-v2 updates remain automatic and transactional.

​
Monitor signer ledger capacity

After install/update and from monitoring, run:
Alert on any failed state.capacity.* check. Warnings begin at 80% of the hard fail-closed limits. Terminal operation details are automatically compacted after 90 days into permanent SHA-256 request-ID replay tombstones; reserved, broadcast, and unknown records are never pruned. Do not delete signer database buckets or restore an older snapshot to make room. Follow the complete snapshot and stale-restore rules in Self-hosted Wallet.

​
Update support contract

Use this order for every existing installation:
  1. Run fased update.
  2. Confirm the version changed when an update was available and the Gateway RPC probe is healthy.
  3. If an old CLI cannot start, fails the update, or reports success without changing the version, bootstrap the runtime once with the matching Local or Hosting installer command below.
  4. Return to fased update for every later release.
The bootstrap replaces application/runtime files, not user state. Do not delete ~/.fased or /home/app/.fased, and do not run fresh onboarding merely to fix an old updater. For Local, WSL, or macOS exact-version repair, follow the canonical exact-tag verification and change only its final invocation to:
Then verify the repaired runtime:
The repair checks out the exact requested tag and pins the managed runtime to that same version. It replaces only a recognized installer-owned fased launcher, installs or refreshes the user service, and verifies that the running Gateway reports the same version. It does not overwrite an unrelated user-managed command or rerun onboarding. On macOS the exact tagged source is built because no managed Linux runtime artifact is used. VPS Hosting bootstrap must run from the provider’s root console. Follow the manual pre-execution verification procedure for the exact release, then use --repair-hosting instead of --hosting only in the final invocation of that already-verified standalone installer. Never recover Hosting by piping a raw repository URL into a shell. An immutable old binary cannot execute updater logic that was introduced in a newer release. That one-time bootstrap is therefore unavoidable for a small set of broken historical builds. It preserves configuration, credentials, wallets, signer state, mining state, sessions, memory, and installed plugin records. After the bootstrap installs the stable external updater, later application versions cannot strand the update command inside an old release directory. The bootstrap is complete only when fased --version, the Doctor header, and the Gateway runtime agree, RPC probe: ok is reported, and plugin doctor is clean. A CLI version alone is not sufficient proof because a legacy service can still be running from an older source checkout. ./install.sh:
  • installs or repairs dependencies
  • rebuilds
  • refreshes the CLI/runtime
  • runs onboarding unless --no-onboard is set

​
Update sequence

  1. check update status
  2. run update
  3. run fased doctor
  4. verify dashboard, wallet, Fased Network, and other critical surfaces
Example:

​
SAT runtime IDs during update

Pre-launch updates keep Satcoin runtime IDs empty unless you explicitly set a test network. After official mainnet launch proof is published, use Mining > Sync to verify the signed manifest and write:
Later releases may include final mainnet IDs, but Sync remains the preferred check because it verifies the live official manifest.

​
Rollback

If a source checkout is bad, roll back to an earlier release tag, then rerun the source installer:
Then verify:

​
Current public boundary

Fresh installs and hosted systems should use the curl bootstrap:
  • curl bootstrap for fresh local machines, WSL2, and hosted VPS
  • fased update for normal updates
  • verified GitHub Release artifacts for supported Linux Local and VPS Hosting installs and updates
  • source checkout builds for macOS and explicit --source-install workflows
  • manual npm install -g @fased/fased is for advanced/local/manual installs, not the recommended hosted VPS setup flow
See Core And Optional Components for channel add-ons, local model servers, browser binaries, and local memory embeddings.