The simplest install on either platform is the bottled Homebrew formula:

Updates flow through the same channel:

Homebrew installs a precompiled binary, so the user does not need a Rust toolchain. The four target tarballs (Intel and Apple-Silicon macOS, x86_64 and aarch64 Linux glibc) are built and published from a developer machine via cargo-release plus the two scripts under scripts/release-*.sh — the published Linux binaries pin glibc to 2.17 for wide compatibility.

Verify the install:

The three components are the crate version, git describe --tags --always --dirty from the build, and the UTC build timestamp. A running binary therefore always identifies the commit it was built from — useful when reporting an issue.

init scaffolds a config directory. It does not materialise the shipped prompts, agent definitions, or fixed-memory files — those are baked into the binary and read from the embedded set on every invocation. The only file init writes is a starter config.lua whose body is entirely commented out, present as a discoverability aid for users who want to start customising. An empty config dir (or no config dir at all) is a valid setup; the runtime falls back to the embedded defaults unchanged.

The path is a suggestion; you can put the config directory wherever you like. On Linux the platform default lookup is ~/.config/ravel-lite/; on macOS it is ~/Library/Application Support/ravel-lite/. If you init at one of those defaults, the trailing guidance changes to "Config is at the default location; ravel-lite will discover it automatically" — no env var or CLI flag needed. The non-default path used in this tutorial keeps macOS and Linux walkthroughs identical and is the precedent most users follow.

After init runs, the directory contains exactly one file:

That file is the customisation surface. It is plain Lua and entirely commented out at scaffold time, so reading the file is the fastest way to discover what you can customise:

The Configuration and prompts reference covers the full Lua API: setters for the active agent and per-phase models, an append_prompt registrator that adds extra guidance to the embedded prompts, and direct writes to ravel.config for headroom and other scalars.

Re-running init against an existing config directory is safe. It does not error and it does not overwrite your config.lua:

--force exists for a narrow purpose: pruning paths that used to ship and have since been removed or renamed. It does not refresh shipped defaults — they live in the embedded set, not on disk — and it deliberately leaves your config.lua untouched.

In day-to-day use you almost never need --force. The one situation that warrants it is upgrading across a release that retires a previously-shipped path: --force removes the now-defunct file or directory so your config tree matches the new layout. The --help text and release notes call out when this matters.

If you used the platform default location, you can skip this section. Otherwise, ravel-lite needs to know where to look. The precedence chain is:

If none of the three resolves to an existing directory, ravel-lite still runs against the embedded defaults — but customisations in your config.lua will not be picked up, because nothing tells the binary where to find it. The recommended workstation setup is to set the environment variable in your shell profile:

Reload the shell or run source ~/.zshrc, then verify:

An empty catalog is valid output — it just means no projects have been registered yet. We will add one in the next chapter.

The --config flag exists for one-off overrides: running an isolated config directory for an experiment, or driving multiple installations from the same shell. It overrides the env var without changing it.

Two signals tell you the install is healthy.

First, ravel-lite version returns a version line — that confirms the binary is on PATH and runs. Second, ravel-lite state projects list returns the empty catalog (or any catalog you have already populated):

That confirms the binary can find a config directory and parse it. There is no third check for shipped prompt files or an agents/ directory — those are embedded in the binary, not on disk, so a missing phases/ or agents/ directory in your config dir is not a fault. If you want to inspect the shipped prompts, the source-of-truth is defaults/ in the Ravel-Lite source tree; the Configuration and prompts reference documents how to override or append to them via Lua.

With the binary installed and the config directory pointed at, you are ready to set up a project — the next chapter introduces the worked-example reading-list-manager that the rest of the tutorial threads through.