An independent installer, upgrader and repair tool for Raft Computer, written in Rust and built on K. It is released separately from Computer and can repair an installation that cannot start.
It implements K's installer contract. K supplies the transaction; this project supplies Computer's release source, installation paths, service commands and first setup. The contract defines the shared behavior; this README covers how to use and develop the Computer adapter.
curl -fsSL https://cdn.raft.build/computer/install.sh | sh
curl -fsSL https://cdn.raft.build/computer/install.sh | sh -s -- --channel alpha
curl -fsSL https://cdn.raft.build/computer/install.sh | sh -s -- --version 1.0.31 --yes
curl -fsSL https://cdn.raft.build/computer/install.sh | sh -s -- repair --version 1.0.31 --yes
curl -fsSL https://cdn.raft.build/computer/install.sh | sh -s -- status
curl -fsSL https://cdn.raft.build/computer/install.sh | CI=1 shOn Windows:
irm https://cdn.raft.build/computer/install.ps1 | iex
& ([scriptblock]::Create((irm https://cdn.raft.build/computer/install.ps1))) --channel alphaThe bootstrap downloads and verifies the installer, runs it, and cleans up its temporary files. It uses a published release. To run code from this checkout, use the native executable produced by the build command below.
If an operation stops before it can be settled (exit code 3), the bootstrap runs the same command once more with the same verified binary before reporting; a second unresolved result is reported as-is, with the cause and the advice to run the same install command again. Users are never asked to run the installer executable themselves.
Linux installers are statically linked against musl, so one binary runs on any distribution regardless of its glibc version (Rocky/RHEL 9, Ubuntu 22.04, Debian 12 and newer are all supported).
| Command | Behavior |
|---|---|
install, upgrade |
Bring the machine to the selected version: install if fresh, adopt a pre-K installation, upgrade a managed installation, or repair a broken one. No command means upgrade in the native CLI and install in the bootstrap; both choose the path from the machine's state. |
repair |
Reinstall a broken installation, preserving credentials, configuration and user files. Held when the installation is healthy. |
status |
Settle interrupted work and report the current installation. Does not reinstall. |
recover |
Recover interrupted work from local state, without selecting a new release. |
| Option | Meaning |
|---|---|
--version V |
Select an exact Computer version. |
--channel NAME |
Select main (default), alpha, or a named feature channel. Resolved once through Hands; mutually exclusive with --version. |
--yes, -y |
Accept the selected version without an attended confirmation. Unattended runs never ask; invocation is consent. |
--allow-downgrade |
Explicitly allow an older target. Otherwise the request is held. |
--json |
Print a structured result instead of the human result line. |
--setup ARGS… |
Entry scripts only (install.sh, install.ps1; on Windows the pasted irm … | iex puts raft-computer on the current session's PATH, so run raft-computer setup /my-server as the next line; $env:RAFT_COMPUTER_SETUP still works for scripts): after a successful install, run raft-computer setup ARGS… with the installed binary. Everything after --setup is passed to setup; put install options before it. Not combinable with --json. Example: curl -fsSL …/install.sh | sh -s -- --setup /my-server. |
raft-computer-installer --version alone prints the installer's own version.
First setup uses raft-computer login when someone is at the terminal. After a
successful login, Computer starts. An unattended fresh install stays stopped and
reports the next step. Upgrades do not repeat login: a running service comes back
running, and a stopped installation stays stopped.
A Computer CLI waiting for its installer is not a running service. The installer attests that CLI's immediate-parent process identity at entry and retains the exclusion only for that operation. Remote service callers remain product processes. Computer CLIs must explicitly declare that they are waiting. A terminal does not establish this role. Upgrading through an older Computer CLI that cannot make this declaration is unsupported; for such machines, support runs the published install command (the bootstrap), which never requires the user to know about or run the installer executable. An undeclared CLI caller is rejected before installation changes. Supported calling CLIs receive the final installer exit code, not background acceptance. The installer lock serializes installation and recovery. If an installer dies but leaves its calling CLI behind, a later recovery may terminate that orphaned CLI; it does not block recovery or count as a service that must be restarted.
Exit codes: 0 succeeded or already up to date; 1 failed or rolled back;
2 held; 3 recovery unresolved (the bootstrap retries the same command
once on this code before surfacing it). Details are recorded under
<RAFT_HOME>/computer/installer/receipts/. Repeating a completed operation ID
returns its unchanged receipt with a historical-result label; use status to
observe the machine now. An unreadable old receipt prevents reusing that request
ID, but does not by itself mark the current installation broken. Active recovery
records remain authoritative until their operation is confirmed finished.
A web upgrade (started by the running service with remote:<its id>) always
ends with a receipt, because its Computer reads nothing else: a refusal before
anything starts, an error, an answer no worker wrote down and a supervisor that
gives up are written as one too (rust/settle.rs, detail.settledBy
fallback). These are create-only: an existing receipt is never replaced. A
request whose operation already started is written as unresolved under that
operation's identity, so its own later run can still finish it; its reason
says "An earlier installation could not be recovered" (the original reason is
detail.requestReason), which is what keeps the request open when a Computer
relays only the reason. A remote:
label that did not come from the service (a leaked one) gets no receipt; a
refusal that cannot otherwise prove the request is its own writes one only for
an id nothing was ever started for.
| Environment | Meaning |
|---|---|
CI, RAFT_COMPUTER_NON_INTERACTIVE=1 |
Run unattended. Otherwise terminal availability determines whether to ask. |
RAFT_HOME, fallback SLOCK_HOME |
Computer's state root; default ~/.slock. |
RAFT_COMPUTER_INSTALL_DIR |
Directory for raft-computer and its sidecar; default ~/.local/bin. For that default, update a supported shell profile or Windows user PATH when needed. Custom directories produce a PATH hint. |
RAFT_COMPUTER_NO_MODIFY_PATH=1 |
Leave PATH configuration unchanged. |
RAFT_COMPUTER_HANDS_ORIGIN, RAFT_COMPUTER_HANDS_APP |
Product release authority; defaults https://hands.build and raft-computer-cli. |
RAFT_COMPUTER_INSTALLER_CHANNEL |
Installer release channel; default main. Separate from Computer's --channel. |
RAFT_COMPUTER_INSTALLER_DL_BASE |
Installer download authority; default https://hands.build/dl/raft-computer-installer. |
RAFT_COMPUTER_INSTALLER_RELEASE_BASE |
Exact static installer release directory containing SHA256SUMS and native/<target>/…; overrides installer channel resolution. |
RAFT_COMPUTER_OPERATION_ID |
Launcher-supplied request ID for replay; generated when omitted. |
HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, NO_PROXY |
Download proxy settings. |
The adapter uses Computer's start, stop, status --json and --version
commands. A live status attestation supplies servicePid, computerVersion and
serviceGeneration; the installer also checks OS process identity. Stopped
installations are checked through a short-lived --version process.
Several state homes (RAFT_HOME) may run one installed binary. An operation
acts only on its own home's Computer: a process on the shared binary whose
environment resolves to another home is left running (on its old image until
that home restarts it). Where the environment cannot be read (Windows, access
denied) the process counts as this home's, as before.
A process of the binary whose first argument is __cli (the raft command an
agent runs) is a short-lived client, not the service: it is never counted as a
running product, stopped or waited for. Its arguments are read from
/proc/<pid>/cmdline, KERN_PROCARGS2 (macOS) or the process command line
(Windows); a process whose arguments cannot be read counts as the product.
Computer raw/gzip and photon_rs_bg.wasm identities come from one Hands
updates/check selection. Exact versions and channels both freeze immutable
Hands release URLs; there is no product CDN manifest fallback. Missing WASM,
cross-release URLs, or hash/size mismatches stop installation before service changes.
photon_rs_bg.wasm is verified against this selection, cached per version,
and published beside its matching binary, including during rollback. Product
bytes run from the installation directory, outside K's slots.
A download that receives no data for 30 s is stalled and its attempt ends
(K's idle timeout, now set explicitly). The installer's own downloads for one
request (a fresh install's or repair's support file and Raft Computer, an
upgrade's support file) retry up to five times, each attempt resuming from
the partial file with a Range request, and all of them, pauses included, end
within 10 minutes; a slow transfer that keeps receiving data may use all of
it. An upgrade's candidate is fetched by K in one attempt with K's size-based
budget (the size over 64 KiB/s plus 30 s: about 14 minutes for the
Computer's gzip) and the same stall timeout. A download that ends stalled
fails with download_stalled; one that runs out of time says the connection
was too slow. Nothing was changed either way. The first worker's 20 minutes
cover a typical upgrade, but not every bound at once: the support file
(10 min), the candidate (~14), the preparation (5) and the handover (six host
calls of up to 2 min and a 5-minute read-back) add up to about 46 minutes.
K downloads, verifies and stages an upgrade's candidate before it hands over. When K stops there without recording an outcome (a failed candidate download), nothing was stopped or replaced: the installer settles K's operation as failed, under K's lock and only while K's transaction is at rest on the source version, and reports the upgrade failed with nothing changed. An operation left open at the handover or later stays unresolved for recovery.
Before anything is stopped, a downloaded candidate (and, after a fresh install
or repair publishes it, the installed copy) must answer --version with its
own version within 120 s. That first run of a new ~150 MB file goes through
the operating system's scan (macOS Gatekeeper/XProtect, Windows Defender),
which can take tens of seconds on a busy machine; a binary that has run
before gets 20 s. For a first run the bound covers starting the process too
(a start still pending at the deadline is abandoned), and a check whose
process outlives its kill is reported as timed out instead of waited for.
Routine commands keep their budget from the moment the process has started. A check that runs out of time fails with candidate_check_timed_out, a
candidate that reports another version or fails to run with
candidate_check_failed; both changed nothing.
A request refused before it starts an operation of its own (held, declined,
downgrade, release not resolved) while an earlier installation is still
unresolved, and before it attempted any recovery itself, fails with
earlier_recovery_pending: nothing was changed, the earlier installation's
records are left for the repair, and the refusal's own code stays in
detail.requestCode. A request that did attempt recovery (resumed the earlier
operation, ran K's recovery, or is the supervisor's next worker after a failed
settlement) or started its own repair stays unresolved
(recovery_unresolved), so the supervisor and the entry script keep retrying.
Receipts carry detail.phasesMs, a JSON object of wall-clock milliseconds per
phase: prepare, download, candidate_check and handover (K's stop,
replace, start and read-back) for an upgrade; prepare, candidate_check,
stop, swap, verify and start for an install or repair.
A service the product runs under a service manager is that manager's to stop
and start, never raft-computer stop/start beside it:
- A systemd unit found at runtime (a user's own unit): the installer leaves
the unit's control group first (
systemd-run --scope) and usessystemctl. The copy in the scope gets the original run's inside-Computer verdict only when the process tree proves it is that copy (its parent runs the same executable bytes and was started by the Computer service);RAFT_COMPUTER_INSTALLER_SCOPEalone exempts nothing. A system unit run as another user than root tries that user's manager (systemd-run --user) when the system manager refuses the scope. When it cannot leave, it goes on only if the unit's actualKillMode=isprocessornone(noted assystemdKillModein the receipt); otherwise (control-group,mixed, or unreadable) it is held, with systemd-run's error as the receipt'sdetail.diagnostic. The original run waits for the copy (at most the supervisor's budgets plus 300 s, holding no lock). In a unit that stops its whole control group (KillMode=control-groupormixed) it is stopped with the unit once the copy stops it; underprocessornoneit keeps waiting until the copy exits, then reads the copy's receipt. If the copy ends without a receipt, the original writes one (escape_failed, orunresolvedonce an operation started). - Raft Desktop's registration (
rust/host_supervisor.rs): format 2 of<RAFT_HOME>/computer/host-lifecycle-owner.jsonnames a launchd agent, a systemd--userunit or a Windows logon task. Stop disables it first, so nothing relaunches the old version during the swap (launchctl disable+bootout;schtasks /Change /DISABLE, a graceful stop,/End); start and rollback enable it and start it again (enable+bootstrap+kickstart;/ENABLE+/Run). The operation is held before anything is touched when the registration is not understood (an unknown format is never read as "not registered"), names another binary path than this installation's, or the target is below itsminComputerVersion. On Windows the installer first leaves the job object the service runs in (CREATE_BREAKAWAY_FROM_JOB), or is held. When a stop disables a supervisor that was enabled, the installer recordscomputer/installer/supervisor-disabled-by-run.jsonand re-enables it afterwards (in this run or the next). Its ownraft-computer start/stopcarryRAFT_COMPUTER_INSTALLER_LIFECYCLE=1, so slock keeps that marker for them; a user's or Raft Desktop's stop or start settles it.
The registration and the supervised exit-code table are contracts owned by
slock; contract/ holds byte-identical copies, pinned by digest in
contract/CONTRACT_FIXTURES. Windows builds also produce
raft-computer-launch.exe (GUI subsystem), which the installer publishes next
to raft-computer.exe: the program the logon task runs. It applies that exit
table (75 relaunches, 0/77/78 stay down, anything else relaunches with backoff)
and stops after five consecutive starts that never reached readiness: it writes
computer/run/supervisor-breaker.json, deletes the task, and exits 0.
K owns <RAFT_HOME>/computer/k. The installer keeps its operation records,
receipts, cached sidecars and recovery files under <RAFT_HOME>/computer/installer.
Repair temporarily retains recovery inputs under quarantine/ while the result
is unresolved. After verification and a durable final receipt, the installer
removes obsolete recovery payloads, downloads and sidecars, retaining only the
current sidecar and small receipts. Interrupted cleanup resumes on the next
command. Computer user data and credentials are preserved. Installations owned
by another package manager are held.
Use Rust 1.89 (pinned in rust-toolchain.toml) and Python 3.11 or newer. Node
is not required for building, running or core verification. On Windows, use
python in place of python3.
macOS and Windows build with the platform's native linker. Linux builds target
musl (x86_64-unknown-linux-musl / aarch64-unknown-linux-musl) so the
installer is a static binary; install the target and a musl-capable linker
first:
rustup target add x86_64-unknown-linux-musl # or aarch64-unknown-linux-musl
sudo apt-get install -y musl-tools # provides musl-gcc (Debian/Ubuntu)python3 scripts/build.py # native executable, bootstrap and manifests
python3 scripts/verify.py # static checks, build and native process scenarios
python3 scripts/verify.py --real # also exercise actual published Computer binariesThe executable is dist/native/<target>/raft-computer-installer (.exe on
Windows). Targets are darwin-arm64, darwin-x64, linux-arm64, linux-x64 and
win32-x64. macOS builds are ad-hoc signed by default; set
RAFT_CODESIGN_IDENTITY to use a Developer ID identity.
See verification/README.md for scenarios, isolated test resources and the distinction between fixture and real-product coverage.
A v<version> tag matching Cargo.toml runs the five-platform build and validation
workflow. Each platform produces one native installer executable, which includes
its supervisor and worker.
scripts/publish.py publishes through the Hands HTTP API: one build containing
all platform binaries and checksums, followed by one release and public download
readback. CI uses HANDS_INSTALLER_DEPLOY_TOKEN; prereleases go to alpha, stable
versions to main. GitHub receives the bootstrap scripts, manifest, checksums and
an archive of the complete release.
The bootstrap resolves the installer channel once and downloads all files from
that immutable release. Static mirrors use the same native/<target>/ layout.
Version tags publish prereleases to alpha and stable versions to main.
The default bootstrap always resolves the installer's main channel, separately
from the Computer version/channel it will install. To promote an already verified
release to another installer channel, run the Promote installer release
workflow with its exact tag and destination channel. It reuses the GitHub release
archive, checks the tag/commit and every asset hash, and downloads the published
Hands bytes again; it does not rebuild them or advance the Computer channel.