# 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.

CraftOS-PC is the emulator; `craftos` is the command-line executable it installs. For the broader upstream documentation index, see [`craftos_pc_glossary.md`](craftos_pc_glossary.md).

Minimum version: **v2.8.3**. `just install` runs `craftos --version` to verify it is on `$PATH` and recent enough; it also checks that `jq` and `luacheck` are installed.

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.

When running headless tests on macOS, prefer passing the app bundle's resource directory explicitly if `craftos` is reached through the `/usr/local/bin/craftos` symlink:

```sh
craftos --headless --rom /Applications/CraftOS-PC.app/Contents/Resources --exec 'print("__TRAPOS_TEST_OK__"); os.shutdown()'
```

## 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.

To verify that CraftOS-PC can boot a computer, not only print its executable version, run:

```sh
craftos --headless --exec 'print("__TRAPOS_TEST_OK__"); os.shutdown()'
```

On macOS, use the `--rom` form shown above if the command fails with `Could not mount ROM`.

## Running tests

`just test` runs `/programs/runtest.lua` headlessly through CraftOS-PC. The runner discovers tests under `/tests`, while the `Justfile` only owns host launch flags, timeout, and success-marker checks. On macOS the recipe passes `--rom /Applications/CraftOS-PC.app/Contents/Resources` because the `/usr/local/bin/craftos` symlink loses ROM auto-discovery; on Linux and Windows no flag is needed. `just ci` runs the same tests after `luacheck`.

## Repository-local launches

`just trapos` launches CraftOS-PC with the TrapOS dev environment: persistent save data rooted at `.craftos` instead of the platform default user-data directory, and read-only mounts of the repository at `/trapos` plus each shipped top-level directory at its ComputerCraft root path (such as `/apis`, `/programs`, `/servers`, `/startup`, and `/tests`). Generated files live under `.craftos/config/` and `.craftos/computer/`, while the root `.gitignore` keeps that state untracked.

`just craftos` launches a vanilla CraftOS-PC with no mounts, persistent under `.craftos-vanilla/` (also gitignored). Use it when a probe should not see TrapOS files — for example, to confirm a behavior is upstream rather than TrapOS-specific.

`just trapos-install` exercises the real ccpm bootstrap (`install-ccpm.lua` → `ccpm update` → `ccpm install trapos`) end-to-end on a fresh, ephemeral CraftOS-PC state. Network-dependent and slower than `just test`, so not part of `just ci`. Override the watchdog with `TRAP_CCLIBS_INSTALL_TIMEOUT_SECONDS` (default `60`).

Pass CraftOS-PC flags directly after the recipe name, for example:

```sh
just trapos --headless --exec 'print("__TRAPOS_TEST_OK__"); os.shutdown()'
just craftos --headless --exec 'print(_HOST); os.shutdown()'
```

See [`docs/adrs/adr-0012-headless-craftos-pc-as-hypothesis-probe.md`](adrs/adr-0012-headless-craftos-pc-as-hypothesis-probe.md) for the canonical headless probe pattern used to verify hypotheses about CC:Tweaked behavior.

`just repl` delegates to `just trapos --cli` for human interactive use only. LLM agents must not run `just repl`.

See [Command-Line Flags](https://www.craftos-pc.cc/docs/cli) for `--headless`, `--exec`, `--script`, `--rom`, and `--mount-*`. See [Error Messages](https://www.craftos-pc.cc/docs/error-messages) for `Could not mount ROM` and other boot-time failures.

## Updating

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