Install Keystone

Keystone is in private beta. Keystone Install is a desktop app. It installs Keystone's command-line tools and their dependencies, and then opens Keystone Studio.

Keystone Install uses Toolchain, the part of Keystone that installs, updates, and rolls back its tools. You can also use Toolchain from a terminal with keystone machine.

Before you begin

You need:

A package link and its SHA-256 checksum from your Keystone contact. Use the exact package you were sent.
A supported system: macOS on Apple silicon, Windows 10 or 11 on x86-64, or Ubuntu 24.04 on x86-64.

Beta packages are unsigned, and the macOS package is not notarized. Your operating system shows a warning when you open the package. Open it only if the checksum matches. Keep Gatekeeper and SmartScreen turned on.

macOS (Apple silicon)

Put the download in its own folder.

In Terminal, get the checksum of the package:

shasum -a 256 ./keystone-install-*-macos-arm64-tester-unsigned.pkg

Compare the result with the checksum you were sent. If they differ, stop.

Install the package:

sudo installer -pkg ./keystone-install-*-macos-arm64-tester-unsigned.pkg -target /

Open Keystone Install from /Applications.
Choose Install Keystone.
When setup is complete, choose Launch Keystone. Studio opens.

Windows (x86-64)

In PowerShell, get the checksum of the ZIP file:

Get-FileHash .\keystone-install-*-windows-x86_64-tester-unsigned.zip -Algorithm SHA256

Compare the result with the checksum you were sent. If they differ, stop.
Choose Extract All. Run all files from the extracted folder.
Double-click Start Keystone Install.cmd.
Choose Install Keystone.
When setup is complete, choose Launch Keystone. Studio opens.

To open Studio later, double-click Start Keystone Studio.cmd.

Ubuntu 24.04 (x86-64)

Install the libraries that Studio needs:

sudo apt-get update
sudo apt-get install libgtk-3-0t64 libwebkit2gtk-4.1-0 libxcb1 libxkbcommon0 libxkbcommon-x11-0

Check the archive against its checksum file:

sha256sum -c keystone-install-*-linux-x86_64-tester-unsigned.tar.gz.sha256

Extract the full archive.
From the extracted directory, run ./Start Keystone Install.sh.
Choose Install Keystone.
When setup is complete, choose Launch Keystone. Studio opens.

To open Studio later, run Start Keystone Studio.sh.

Check the machine

Open a new terminal.
Run:
```
keystone machine status
```

This command reads the installation and changes nothing. On a healthy machine, the output ends with these two lines:

READY machine installed healthy version=aggregate-cf45cf2b4ea96dbb
NEXT no action required

If your shell cannot find keystone, the commands are in ~/.keystone/toolchain/active/bin.

If the status shows a problem, run keystone machine doctor. It explains the problem and gives the repair.

Update, repair, and roll back

In Keystone Install, open Manage this machine. It shows only the actions that the current status allows.

From a terminal, every change starts as a preview:

keystone machine update                  # show the update plan
keystone machine update --apply          # apply the plan you reviewed
keystone machine rollback --to previous  # go back to the previous installation

An update keeps the previous installation, so you can always roll back to it.

Developer setup

Use Developer setup only if you want to work on Keystone's source. It clones the Keystone repositories into a folder you choose, installs the build dependencies, and builds the commands.

Before you start, sign in to the GitHub CLI (gh) with an account that can read the Keystone repositories. After setup, use kstoolchain to manage source builds.

If something goes wrong

If Keystone Install stops, refuses to continue, or reports that no complete release is available:

Leave the machine as it is.
Open Manage this machine.
Choose Copy support summary.
Send the summary to your Keystone contact. Include the last step you completed.

The summary leaves out credentials, file paths, and machine identifiers.