Install CraftOS-PC

CraftOS-PC is the local harness used to run this repo's Lua outside of Minecraft. See ADR-0005 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.

Minimum version: v2.8.3. just install runs craftos --version to verify it is on $PATH and recent enough; it also checks that jq, luacheck, and openssl 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.

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

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:

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 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, make it executable, and symlink it into $PATH:

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

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:

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:

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 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 for --headless, --exec, --script, --rom, and --mount-*. See 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.

5.5 KiB Raw Blame History