Quickstart and Installation¶

This page gets a local Moraine stack running on macOS or Linux.

Install¶

The recommended install path is the PyPI package with uv:

uv tool install moraine-cli

Upgrade through the same tool manager:

uv tool upgrade moraine-cli

If you prefer release bundles, run the installer:

curl -fsSL https://raw.githubusercontent.com/eric-tramel/moraine/main/scripts/install.sh | sh

The bundle installer places binaries in ~/.local/bin by default and writes ~/.moraine/config.toml when that file does not already exist. Add ~/.local/bin to PATH if your shell does not find moraine.

Guided Setup¶

Run the guided setup once after installing, or rerun it later to repair a broken config and install or update agent harness integrations:

moraine setup

For non-interactive config creation, select the config mode explicitly:

moraine setup config --yes

To back up and replace an invalid config non-interactively, opt into repair:

moraine setup config --repair --yes

To configure every supported harness integration non-interactively, make the broad integration scope explicit:

moraine setup integrations --all --yes

Preview those integration changes without writing files or running external commands:

moraine setup integrations --all --dry-run

The Claude Code and Codex plugins, plus global MCP registrations, can expose host-wide Moraine session history to that harness. moraine setup asks before making those changes; for project-scoped or custom harness setup, see Agent MCP Search → Install.

Start Moraine¶

Start ClickHouse, ingest, and the unified MCP/monitor backend:

moraine up

Every moraine up includes the backend. Existing loopback configurations with backend.start_on_up = false are accepted for upgrade compatibility but no longer suppress it. Non-loopback binds require an explicit true value so an upgrade cannot unexpectedly expose the unauthenticated monitor API. Moraine does not install an OS login service; run moraine up after a reboot.

Check service health:

moraine status

moraine status prefers the live backend's /api/v1/status response and automatically falls back to a direct database read when the backend is unreachable. Human output labels the source as daemon API or direct DB; JSON output adds the compatible top-level data_source field with daemon_api or direct_db. It also connects directly to the backend MCP socket, completes an initialize handshake, sends the MCP ping health check, and reports the result as mcp_health in JSON output. This checks Moraine's shared MCP service without starting Codex, Claude Code, or another harness.

When the daemon API is available, status also reports a Query Pressure section (and JSON query_pressure object) with per-profile running, queued, and rejected counts plus a content-free resource-limit event total. These counters describe the local backend process only; direct-database fallback omits them. They never include SQL, query text, credentials, or user content.

For a local ClickHouse process started by moraine up, Moraine keeps a small supervisor running after startup. If ClickHouse exits unexpectedly, the supervisor waits 1, 2, 4, 8, then 16 seconds between at most five consecutive replacement attempts. Each replacement must become query-ready before recovery is recorded. A generation that remains ready for five uninterrupted minutes resets the consecutive-failure budget. After the retry budget is exhausted, moraine status reports ClickHouse stopped/unhealthy; run moraine logs clickhouse for the exit and retry history, then moraine up to start a fresh recovery budget. External ClickHouse endpoints are never adopted or restarted.

After starting the backend, open the monitor UI:

http://127.0.0.1:8080

The backend HTTP listener binds to 127.0.0.1 by default. Before changing the bind, read the experimental HTTP bind guard; it is startup groundwork, not HTTP request authentication.

Run agent sessions normally. As Moraine indexes session files, the monitor and status output should show fresh ingest activity.

Add MCP Retrieval¶

For Codex and Claude Code, moraine setup registers the Streamable HTTP MCP endpoint served by the unified backend:

http://127.0.0.1:8080/mcp

Both harnesses connect to the same backend process; they do not start a per-client moraine run mcp tunnel. Keep the backend running with moraine up. Other harnesses and project-scoped compatibility setups may still use the stdio launcher and its Unix-socket/embedded fallback. See Agent MCP Search → Install.

Use moraine setup to connect your agent harnesses. In an interactive terminal, setup shows all supported harnesses selected by default; use the arrow keys to move, Space to cycle a harness through ingest/plugin-MCP/off choices, and Enter to apply the selected integrations:

moraine setup

You can also target harness MCP/plugin setup directly, which is useful for rerunning setup after installing a new harness CLI. Direct targets do not change ingest source selections:

moraine setup integrations claude-code codex hermes kiro-cli kimi-cli qwen-code nac opencode cursor pi-coding-agent omp prime-agent --yes

Preview targeted MCP/plugin changes without touching host agent config:

moraine setup integrations claude-code codex hermes kiro-cli kimi-cli qwen-code nac opencode cursor pi-coding-agent omp prime-agent --dry-run

The Claude Code, Codex, and Hermes plugins bundle Moraine search, realtime, and sanitized bug-report guidance. moraine setup installs those plugins for default user-scoped setup. For Kiro CLI, setup registers global MCP, installs managed search and realtime guidance under $KIRO_HOME/steering when KIRO_HOME is set (or ~/.kiro/steering otherwise), and points the setup-owned ingest source at the matching sessions/cli directory. It also registers MCP directly or writes global MCP config for supported harnesses such as Qwen Code, Kimi CLI, NAC, OpenCode, Cursor, Pi Coding Agent, OMP, and Prime Agent. Prime Agent setup manages $PRIME_AGENT_CODING_AGENT_DIR/settings.json and skills/moraine (defaulting to ~/.prime/agent); stop Prime Agent and start a fresh session after setup. For NAC, setup merges [mcp_servers.moraine] into the config at NAC_HOME, then XDG_CONFIG_HOME/nac, then ~/.config/nac, without replacing model, storage, sandbox, or unrelated MCP settings. It adds a nac_sqlite source only for the default store or an absolute storage.store_path; relative paths and per-launch nac --store-path overrides need the manual source snippet described in Agent MCP Search → NAC. These user-scoped integrations can search the host-wide Moraine history visible to your user, so enable them only in trusted harness environments. Qwen registration does not enable Qwen's MCP trust option. After at least one integration is configured, setup runs the same backend MCP initialize and ping check. An unhealthy or stopped backend makes setup exit nonzero while leaving the per-target result as configured, so plugin installation is distinguishable from MCP service health. Run moraine up and rerun setup; no harness session is launched by this check. Dry runs and manual-only targets do not contact the backend.

The same Codex marketplace also contains the contributor-only moraine-dev plugin for Moraine maintainers; end users should install moraine@moraine.

The MCP server uses the same config resolution rules as the rest of Moraine, with MORAINE_MCP_CONFIG taking precedence over the generic MORAINE_CONFIG. For manual cleanup, project-scoped setup, and other custom setup, see Agent MCP Search.

Common Commands¶

Install From Source¶

Source builds are useful for development and local testing:

git clone https://github.com/eric-tramel/moraine.git
cd moraine
cargo build --workspace --locked
MORAINE_SOURCE_TREE_MODE=1 cargo run -p moraine -- up

MORAINE_SOURCE_TREE_MODE=1 tells the control command to run service binaries from target/debug. A source install requires the moraine-ingest and moraine-mcp service binaries; moraine-monitor is an optional deprecated compatibility alias and is not required. For installed binaries, keep moraine-ingest and moraine-mcp beside the moraine control binary, or set MORAINE_SERVICE_BIN_DIR to the directory containing those service binaries.

Stop¶

Stop the local stack when you are done:

moraine down