Install and update One#

The One release archive targets Linux x86_64. The executable and its adjacent distribution/ directory form one installation: do not copy the executable away from the semantic packages, normalizers, analyzers, tools, and providers it resolves.

Verify before extraction#

Download the archive together with its .sha256, .sig, and .pem files. Verify both content and the release-workflow signing identity:

sha256sum -c one-linux-x86_64.tar.sha256
cosign verify-blob \
  --certificate one-linux-x86_64.tar.pem \
  --signature one-linux-x86_64.tar.sig \
  --certificate-identity https://github.com/muijf/one/.github/workflows/release.yml@refs/tags/<version> \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  one-linux-x86_64.tar

A matching checksum without a valid signing identity proves only byte integrity, not release origin.

For the first installation, extract the verified archive into a versioned directory. When One is already installed, use its installer with the exact digest from the verified checksum file:

one bundle install \
  --archive one-linux-x86_64.tar \
  --digest sha256:<verified-archive-digest> \
  --platform linux-x86_64 \
  --destination /absolute/path/to/new-installation

The destination must be absent. Installation verifies the complete archive and distribution evidence before making the directory available, and retains an installation.json report beside the executable and distribution/. The digest pins the downloaded bytes; release-origin verification remains the separate signature check above.

Add the complete installation directory to PATH. Confirm the selected command version:

one --version

Work offline#

After downloading and verifying the archive, prepare and check a project with network access denied:

one setup --offline
one check --offline

Every selected package and tool must already be available at its exact locked identity in the distribution or local stores. Project-specific inputs may require preparation before going offline.

For distribution maintainers, one bundle assemble assembles exact published packages and Build evidence into a distribution, and one bundle archive packages a verified distribution with its executable. one bundle install validates and installs that exact archive. Their help lists the required inputs; distribution contents become available to a project only through its explicit selections and normal preparation.

Offline mode never substitutes a nearby release, silently drops an input, or weakens admission because a registry is unavailable.

Update without changing projects implicitly#

Install a new verified archive beside the current version, inspect it, then change the user's explicit PATH or launcher selection. Installing a new One release does not rewrite project source, one.lock, local execution bindings, plans, artifacts, journals, or evidence.

Run the new executable against each project deliberately:

one sync --output one.lock.proposed
one check
one verify

sync --output writes a reviewable lock proposal and leaves one.lock unchanged. The following checks still use the accepted lock. Accept a reviewed source-and-lock transaction explicitly as described in dependencies and toolchains; changing the executable is not a reason to accept new selections. Pre-stable source changes use the one current grammar; update source and lock together rather than retaining parallel old and new project forms.

Roll back or uninstall#

To roll back the tool, restore the launcher or PATH selection to a previously verified intact archive. This does not roll back a deployed system or rewrite effects; release rollback follows an explicit recovery plan.

Uninstall by first selecting another installation, confirming no running One process uses the old directory, and then removing that complete versioned archive directory. Project .one/ state belongs to each project and is not installation residue. Use one clean, one gc, or one reset local only according to their owner-aware retention rules.

Next: build your first system or read dependencies and toolchains.