macOS installer and Runner

Documentation · Português · Linux · Windows

Install, configure, then run

Use macOS 13.5 or newer, on Intel x64 or Apple Silicon ARM64, with a modern WebGL browser. The managed Node.js version follows Node.js 24's macOS requirements. The 0.2.1 package refreshed on 13 October 2026 includes these launchers, as do complete archives generated by build_release.py.

Intel Macs require Apple's Command Line Tools (or a selected Xcode installation with its compiler and SDK) for the dependency source build described below. Homebrew is not required.

1. Extract the complete new archive or use a checkout containing Install macOS.command, in a writable local folder. Keep all project files together.

2. Open Install macOS.command in Finder. It opens Terminal and prepares the installation. You can also open Terminal in the project directory and run:

   bashCopy

   bash "./Install macOS.command"

3. The installer detects the native architecture, reuses verified local tools, downloads missing tools inside the extracted folder, installs locked dependencies and prepares the frontend. Answer the configuration questions. Enter keeps the displayed value; Ctrl+C cancels without saving the answers.

4. It prepares the database and creates Gravewright Runner.command beside itself, then exits without starting the server. Open that generated file in Finder, or run:

   bashCopy

   bash "./Gravewright Runner.command"

5. Open http://127.0.0.1:3000 and create the first owner account. Keep the Terminal window open; Ctrl+C stops the application. Closing the browser does not stop it.

The generated Runner uses the prepared Python and saved settings without installation questions, dependency downloads or npm builds. Rerun the installer to change saved settings, repair dependencies or prepare new/moved project files. Paths with spaces and Unicode are supported; quote filenames. A .command launcher is a Terminal script, not a signed .app bundle.

Permissions and tools

macOS's Bash 3.2 is supported; installing a newer shell or Homebrew is not required. The bootstrap uses curl, system CA trust, tar/gzip and shasum -a 256 or another supported SHA-256 utility. Run it as your regular user; missing Python, uv and Node.js are prepared privately, without sudo, global package installation or permanent PATH/shell-profile changes.

The installer selects darwin-x64 or darwin-arm64 according to the running architecture; compatible tools must match. Internet is required for missing downloads. Verified tools are reused from this installation. Python preparation uses uv sync --locked --no-dev in a private environment; frontend preparation uses npm ci --include=dev --include=optional and npm run build when needed. Unchanged frontend inputs/outputs are reused. The developer .venv and source lock files are preserved. Docker and Redis are not needed for this local profile.

Intel dependency compilation

Cryptography removed official macOS x86_64 support and Intel wheels in version 49; see its changelog. Gravewright builds the locked cryptography 50.x release locally on Intel. This is a Gravewright-maintained source-build path covered by our platform CI, not restored upstream Intel support. The locked cryptography version is unchanged.

The build needs Apple's xcrun-selected SDK, Clang, Make and Perl. If they are missing, the interactive installer starts Apple's system dialog with:

xcode-select --install

Finish the Apple installation, then rerun Install macOS.command. Gravewright does not wait for the system dialog to finish. Installer --check does not open it: it exits with an instruction to install the missing tools and retry. A full, correctly selected Xcode installation can also provide them. The cryptography source-build guide describes the compiler/library requirements.

With those Apple prerequisites available, Gravewright downloads SHA-256-pinned Rust components, builds a static private OpenSSL and compiles cryptography against them. It uses Rust 1.99.0 (rustc, Cargo and the standard library) without rustup, and OpenSSL 3.5.9 LTS, without Homebrew. The first Intel installation can take several minutes longer; verified prepared tools, OpenSSL and build caches are reused. Offline reuse requires a completed earlier preparation, including the compiled dependency and its cached inputs.

On both Mac architectures, the installer sets AUTOBAHN_USE_NVX=0 for dependency preparation, using Autobahn's Python fallback instead of its optional native NVX extension. This avoids requiring that optional compiler build on Apple Silicon, including macOS 13.5/14. It does not remove Intel's cryptography compiler/SDK requirement. Normal Runner startup performs no compilation.

If Finder reports a permission error after extraction, use Terminal in the project folder:

chmod u+x "Install macOS.command"

The generated Runner is executable. If macOS blocks a downloaded script, use Apple's per-item Privacy & Security → Open Anyway flow only for a download you trust; see Apple's instructions. Do not remove security settings globally. Running bash is also useful when diagnosing a script's ordinary execute-permission problem.

Configuration and storage

The installer creates/completes the project's .env from .env.example, preserving saved values, its private secret and custom settings. It asks for table name, language, port, modules folder, join codes, snapshots, campaign exports and tunnel access. Relative database/media/module paths are resolved from the project root. Selecting pt-BR installs and activates the verified official Translator; a verified installed package can be reused offline. The official Marketplace is configured automatically when no catalog is configured. Existing custom catalogs are preserved, and verified official settings are reused offline. Unattended --check does not configure it.

--data-dir relocates Runner state, not the database or uploads; configure those in .env. Set GRAVEWRIGHT_RUNNER_ROOT to an explicit absolute or project-relative path before installation to use a different private-tool directory, for example in an isolated test. It does not change HOME or import configuration from another installation. Moving the project requires installation again because its prepared environment and frontend state are associated with its source location.

Local execution, updates and backups

The Runner binds HTTP only to 127.0.0.1, with one server process and in-memory Channels. Debug remains off, while host/origin, CSRF, session and campaign checks stay active. --no-browser prints the address without opening the default browser. The installer can allow a separately managed local tunnel agent, but does not install tunnel software. For direct LAN access or public HTTPS, follow deployment.

Stop the Runner before changing settings or backing up. Preserve the configured database, private media and project .env together; also retain Runner state for update recovery. Migrations can make older application versions incompatible. Supported managed updates replace project files and regenerate the macOS launcher; immutable copies in .runner-launchers keep the running launcher independent of those replacements. For manual updates or a moved project, run the new folder's installer before starting. See deployment and rollback.

Reinstall the refreshed 0.2.1 package

The 13 October 2026 refresh preserves version 0.2.1, channel stable, Alpha stage and Gravewright-0.2.1-django.zip. Hosts already on 0.2.1 do not receive an automatic same-version update. Download the refreshed ZIP and its matching SHA-256 file; do not reuse the earlier archive's checksum.

Stop the Runner and back up project .env, configured database/media/module paths and Runner state. Replace the application files with the complete refreshed package in the existing installation folder, preserving configuration and data. Open Install macOS.command again and use the regenerated Runner. The entrypoint and supporting scripts must be replaced together. If moving the project, preserve storage paths and prepare the new location with the installer.

SIGHUP follows the orderly Runner shutdown path, including supervisor cleanup. An interrupted update transaction is recovered on the next start; preserve .runner-launchers/ and updates/ with Runner state. See the bilingual 0.2.1 refresh notes. The native CI matrix includes Intel and Apple Silicon; consult its workflow results for actual platform validation.

Unattended checks and troubleshooting

bash "./Install macOS.command" --check --no-pause --data-dir "data/check"
bash "./Gravewright Runner.command" --check --no-browser --data-dir "data/check"

Installer --check prepares tools/dependencies/frontend, writes configuration, migrates the database and generates the Runner without questions or server startup. Runner --check validates the prepared application and can migrate/collect static assets. Neither is read-only. Use a disposable project copy and explicit directories for experiments.

Installer flags are --check, --data-dir PATH, --port NUMBER, --no-browser, --no-pause and --help. Runner flags are --check, --data-dir PATH, --port NUMBER and --no-browser. --port applies only to that run. After a successful installation, unchanged tools/packages/assets can be reused with UV_OFFLINE=1 and npm_config_offline=true; fresh or changed dependencies still need downloads. See uv's offline setting.

The POSIX smoke test installs into a disposable source/tool/state fixture without changing HOME or personal configuration. It covers quoted/Unicode paths, offline reuse, real HTTP readiness and graceful shutdown. The native CI workflow runs Linux and Intel/Apple Silicon macOS jobs; browser behavior is covered separately by the project's browser tests.

All paths in the storage table are relative to the extracted project. data/runner/tmp/ holds bootstrap temporary files. Explicit relative state/tool overrides resolve from this project, never from the caller's working directory.