# Install CraftOS-PC

CraftOS-PC is the local harness used to run this repo's Lua outside of Minecraft. See [ADR-0005](adrs/adr-0005-craftos-pc-harness.md) for why.

Minimum version: **v2.8.3**. `just install` runs `craftos --version` to verify it is on `$PATH` and recent enough.

The upstream installation page is https://www.craftos-pc.cc/docs/installation. The notes below pin the version we test against and add a SHA-256 verification step.

## macOS

There is no Homebrew cask, so the install is a manual drag-to-Applications from the official GitHub release.

```sh
# 1. Download the dmg and the published hashes.
curl -L -o ~/Downloads/CraftOS-PC.dmg \
  https://github.com/MCJack123/craftos2/releases/download/v2.8.3/CraftOS-PC.dmg

# 2. Verify the SHA-256.
curl -sL https://github.com/MCJack123/craftos2/releases/download/v2.8.3/sha256-hashes.txt \
  | grep CraftOS-PC.dmg
shasum -a 256 ~/Downloads/CraftOS-PC.dmg
# The two hashes must match.

# 3. Mount, install, unmount.
hdiutil attach ~/Downloads/CraftOS-PC.dmg -nobrowse
rm -rf /Applications/CraftOS-PC.app
cp -R "/Volumes/CraftOS-PC/CraftOS-PC.app" /Applications/
hdiutil detach "/Volumes/CraftOS-PC"

# 4. Clear Gatekeeper quarantine so the first launch is not blocked.
xattr -dr com.apple.quarantine /Applications/CraftOS-PC.app
```

The binary is not on `$PATH` by default. Add a symlink so `just check-craftos` can find it:

```sh
ln -sf /Applications/CraftOS-PC.app/Contents/MacOS/craftos /usr/local/bin/craftos
```

User data (computer state, settings) lives in `~/Library/Application Support/CraftOS-PC` and survives a reinstall — the steps above only touch the `.app` bundle.

## Windows

Download `CraftOS-PC-Setup.exe` from the [latest release](https://github.com/MCJack123/craftos2/releases/latest) and run it. The installer puts `craftos.exe` on `$PATH`.

User data: `%appdata%\CraftOS-PC`.

## Linux

Download `CraftOS-PC.x86_64.AppImage` from the [latest release](https://github.com/MCJack123/craftos2/releases/latest), make it executable, and symlink it into `$PATH`:

```sh
chmod +x ~/Downloads/CraftOS-PC.x86_64.AppImage
sudo ln -sf "$HOME/Downloads/CraftOS-PC.x86_64.AppImage" /usr/local/bin/craftos
```

User data: `~/.local/share/craftos-pc`.

## Verify

```sh
craftos --version
```

Must report `CraftOS-PC v2.8.3` or newer. Once this works, `just install` will succeed.

## Updating

Repeat the steps above against the newer release. The bundle replacement is in-place; the user data directory is preserved.