Installation & Configuration

This page starts with the installed product flow. Source-checkout and contributor setup are lower down.

Quick Install

Install from a checksummed GitHub release:

curl -fsSL https://github.com/lemoncrow-lab/lemoncrow/releases/latest/download/install.sh | bash

What the installer does:

downloads a pre-compiled LemonCrow binary for your platform from the latest release (checksum-verified)
installs it to ~/.local/bin/
adds the directory to PATH in your shell profile

The binary is self-contained — no git, uv, npm, or node required at install time. No account or login is required; LemonCrow runs fully locally.

Prefer to build from source? Run the source installer from a checkout:

bash scripts/local.sh

Full Developer Install

For host integrations, background services, and the optional visualization stack, install from a repo checkout using the dev installer:

git clone https://github.com/lemoncrow-lab/lemoncrow.git
cd lemoncrow
bash scripts/local.sh --local

The dev installer:

installs lc and lc mcp as user-level console commands in ~/.local/bin
clones or updates LemonCrow under ~/.local/share/lemoncrow
initializes ~/.lemoncrow
starts the detached servicectl loop
attempts to start the optional visualization stack when npm is available
installs host integrations when compatible CLIs are found on PATH

The dev installer uses uv at install time to create a managed tool environment. After install, lc and lc mcp run directly from that environment; normal CLI usage does not shell through uv run.

Verify the install:

lc --version
lc mcp --version
lc background status

Useful Installer Variants

Skip host integrations:

curl -fsSL https://raw.githubusercontent.com/lemoncrow-lab/lemoncrow/main/scripts/local.sh | bash -s -- --no-hosts

Skip auto-starting background services:

curl -fsSL https://raw.githubusercontent.com/lemoncrow-lab/lemoncrow/main/scripts/local.sh | LEMONCROW_NO_SERVICECTL=1 bash

Skip auto-starting the visualization stack:

curl -fsSL https://raw.githubusercontent.com/lemoncrow-lab/lemoncrow/main/scripts/local.sh | LEMONCROW_NO_STACK=1 bash

Install from a local checkout instead of GitHub:

bash scripts/local.sh --local

Install host + universal MCP artifacts into the current project (instead of user-global host config):

bash scripts/local.sh --local --workspace .

Uninstall

Remove LemonCrow with the uninstall script:

bash scripts/uninstall.sh          # remove LemonCrow; your data under ~/.lemoncrow is preserved
bash scripts/uninstall.sh --purge  # remove LemonCrow and all LemonCrow-managed local state

lc uninstall removes host integrations and wrappers only; use the script above to remove the runtime itself.

Runtime Modes After Install

Default Runtime

No HTTP server is required for normal usage.

lc ... is the main CLI
lc mcp is the MCP server used by host integrations
lc background ... manages background services and auto-updates

If npm is installed and LEMONCROW_NO_STACK=1 was not set during install, the installer will also register the visualization stack as a background service for you.

Background Services & Auto-Update

LemonCrow uses your OS-native manager (systemd on Linux, launchd on macOS) to ensure background tasks and the visualization stack are always running.

# Check service health and auto-update status
lc background status

# View background logs
lc background logs controller
lc background logs stack

# Restart the entire stack (e.g. after a manual code change)
lc background restart

Auto-Update

The background controller periodically checks your git repository for updates. When found, it automatically:

Pulls the latest code.
Syncs dependencies using uv.
Restarts the services to apply changes.

Optional UI Stack

Manage the visualization UI as a background service:

lc background restart  # Restarts both controller and stack

Or control the native stack manually:

lc stack start

Then open:

http://localhost:3125 for the frontend
http://localhost:8787 for the service API

Other stack commands:

lc stack status
lc stack logs
lc stack stop

Optional HTTP Service Without the UI

If you want the service API without the full stack:

LEMONCROW_REQUIRE_AUTH=false lc service start --host 0.0.0.0 --port 8787

For authenticated deployments, set LEMONCROW_API_KEY and keep LEMONCROW_REQUIRE_AUTH=true.

Background Controller Variables

The installer registers background services by default.

lc background status
lc background logs

Manual job control is available too:

lc worker enqueue consolidate_playbooks
lc worker run-once
lc worker list

Installer Behavior Variables

Variable	Default	Description
`LEMONCROW_NO_HOSTS`	`0`	Skip host integration install scripts
`LEMONCROW_NO_SERVICECTL`	`0`	Skip auto-registering background services during install
`LEMONCROW_NO_STACK`	`0`	Skip auto-registering the visualization stack service
`LEMONCROW_LOCAL`	`0`	Install from the current checkout in editable mode

Storage Backends

SQLite (default)

SQLite is the default install mode and does not require any extra setup.

store root: ~/.lemoncrow by default
queue-backed worker jobs are supported
good default for local usage, single-user environments, and most host integrations

Store layout:

.lemoncrow/
├── lemoncrow.db          # SQLite store (blocks, traces, rubrics, jobs)
├── blocks/             # Markdown mirrors of Playbooks
├── rubrics/            # YAML mirrors of rubrics
└── traces/             # JSON mirrors of recorded traces

PostgreSQL (optional)

Use Postgres when you want shared storage, central deployment, or multi-writer operation.

LEMONCROW_STORAGE_BACKEND=postgres \
LEMONCROW_DATABASE_URL=postgresql://user:pass@localhost:5432/lemoncrow \
lc init

pgvector (optional)

Embedding-based similarity search is optional and additive:

LEMONCROW_STORAGE_BACKEND=postgres \
LEMONCROW_DATABASE_URL=postgresql://... \
LEMONCROW_VECTOR_SEARCH_ENABLED=true \
LEMONCROW_EMBEDDING_MODEL=text-embedding-3-small \
lc init

Environment Variables

Core

Variable	Default	Description
`LEMONCROW_ROOT`	`~/.lemoncrow`	Main runtime store root
`LEMONCROW_STORE_ROOT`	`~/.lemoncrow`	Alias for `LEMONCROW_ROOT`
`LEMONCROW_LESSONS_ROOT`	workspace-relative	Optional git-tracked lessons root

Storage

Variable	Default	Description
`LEMONCROW_STORAGE_BACKEND`	`sqlite`	`sqlite` or `postgres`
`LEMONCROW_DATABASE_URL`	`""`	PostgreSQL DSN when backend is `postgres`
`LEMONCROW_VECTOR_SEARCH_ENABLED`	`false`	Enable pgvector similarity search
`LEMONCROW_EMBEDDING_DIM`	`1536`	Embedding dimension
`LEMONCROW_EMBEDDING_MODEL`	`text-embedding-3-small`	Embedding model name

Background Controller

Variable	Default	Description
`LEMONCROW_NO_SERVICECTL`	`0`	Skip auto-starting `servicectl` during install
`LEMONCROW_SERVICECTL_INTERVAL_SECONDS`	`60`	Poll interval for the detached loop
`LEMONCROW_SERVICECTL_MAINTENANCE_INTERVAL_SECONDS`	`21600`	Periodic maintenance enqueue interval

Optional Stack

Variable	Default	Description
`LEMONCROW_NO_STACK`	`0`	Skip auto-starting the optional stack

Optional HTTP Service

Variable	Default	Description
`LEMONCROW_SERVICE_HOST`	`127.0.0.1`	Service bind host
`LEMONCROW_SERVICE_PORT`	`8787`	Service port
`LEMONCROW_REQUIRE_AUTH`	`false`	Require Bearer auth
`LEMONCROW_API_KEY`	`""`	Bearer token for authenticated service mode

MCP

Variable	Default	Description
`LEMONCROW_SERVICE_URL`	unset	Remote service URL; when set, core MCP calls route to this service
`LEMONCROW_ADDITIONAL_DIRS`	`""`	Extra directories the edit tools may write to (see below)

Widening the edit write boundary

LemonCrow's read-only tools (read, grep, search, explore) accept any absolute path. Its write tools (edit, batch edit, and bash's write confinement) are deliberately confined to the workspace root, plus /tmp, which is always writable. Anything else has to be opted in explicitly. An edit outside the boundary fails with edit path escapes the workspace root.

There are three supported ways to widen it:

Route	Scope	Takes effect
`permissions.additionalDirectories` in `~/.claude/settings.json` or `~/.claude/settings.local.json`	all workspaces	immediately (live)
`permissions.additionalDirectories` in `<workspace>/.claude/settings.json` or `settings.local.json`	that workspace	immediately (live)
`LEMONCROW_ADDITIONAL_DIRS` env var on the `lc` MCP server entry (`lc settings set mcp.additional_edit_dirs ...`)	that MCP process	after a reconnect

All four settings files are read, and each is read from both the nested permissions.additionalDirectories key (what Claude Code's --add-dir flag and /permissions UI write) and the legacy top-level additionalDirectories key:

{
  "permissions": {
    "additionalDirectories": ["~/notes", "/srv/shared/plans"]
  }
}

Those files are re-read on every edit call (mtime-checked), so adding, editing, or deleting one applies immediately — no restart, no reconnect. The env var is read once at process start like any MCP server env var, so changing it requires restarting the lc MCP connection. It is :-separated (PATH-style); a comma is not a separator, so a directory whose name contains one is listed as-is:

lc settings set mcp.additional_edit_dirs "$HOME/notes:/srv/shared/plans"

Every entry — env var or settings file — must be an absolute path once a leading ~ is expanded. Relative entries (notes, ., ..) are skipped with a warning rather than resolved against the MCP server's working directory. Entries that resolve to a filesystem root (/) or to your whole home directory (a bare ~) are refused with a warning naming the source, so a cloned repo shipping a .claude/settings.local.json that asks for / grants nothing. The other entries in the same list are still honored.

Directory matching is component-wise, not prefix-based: allowing /srv/plans does not allow /srv/plans-secret. A settings file that fails to parse is skipped with a warning naming the file (lc MCP server log) and grants nothing.

LEMONCROW_ADDITIONAL_DIRS is the only variable that widens the write boundary. The similarly named LEMONCROW_RETRIEVAL_ADDITIONAL_DIRS (lc settings set retrieval.additional_dirs) only adds directories to code search/indexing and never grants write access.

Telemetry

Anonymous remote telemetry is on by default. Turn it off with lc telemetry remote off, and back on with lc telemetry remote on. The kill switches DO_NOT_TRACK=1 and LEMONCROW_TELEMETRY=off suppress remote telemetry entirely. See Privacy & network behavior for exactly what is and is not sent.

Variable	Default	Description
`LEMONCROW_TELEMETRY`	on (remote)	Remote telemetry is on by default; `off`/`0`/`false`/`no`, or `DO_NOT_TRACK=1`, disables it

If you are developing LemonCrow itself instead of using the installed product:

cd lemoncrow
uv sync --all-extras
lc init

Contributor verification flow:

make verify

When working from multiple git worktrees, bootstrap each worktree once with:

make worktree-env

If .env.worktree is present, make start and make restart automatically load it so each worktree gets its own ports and .lemoncrow-worktree runtime root.

Per-Agent Host Setup

After installation, use the host-specific guides if you want to inspect or customize integration:

Optional Zoekt Backend

Zoekt is not bootstrapped by default. LemonCrow uses its internal code index, local embeddings, and ripgrep unless an existing Zoekt runtime is detected.

LEMONCROW_ZOEKT_MODE=off (default): never probe or route to Zoekt.
LEMONCROW_ZOEKT_MODE=installed: use Zoekt only when its binaries are already installed or provided through LEMONCROW_ZOEKT_BIN.
LEMONCROW_ZOEKT_MODE=managed: allow LemonCrow to provision and run the pinned Zoekt container through Docker for large repositories.

Navigation Menu

Uh oh!

Installation & Configuration

Quick Install

Full Developer Install

Useful Installer Variants

Uninstall

Runtime Modes After Install

Default Runtime

Background Services & Auto-Update

Auto-Update

Optional UI Stack

Optional HTTP Service Without the UI

Background Controller Variables

Installer Behavior Variables

Storage Backends

SQLite (default)

PostgreSQL (optional)

pgvector (optional)

Environment Variables

Core

Storage

Background Controller

Optional Stack

Optional HTTP Service

MCP

Widening the edit write boundary

Telemetry

Per-Agent Host Setup

Optional Zoekt Backend

Uh oh!

FilesExpand file tree

installation.md

Latest commit

History

installation.md

File metadata and controls

Installation & Configuration

Quick Install

Full Developer Install

Useful Installer Variants

Uninstall

Runtime Modes After Install

Default Runtime

Background Services & Auto-Update

Auto-Update

Optional UI Stack

Optional HTTP Service Without the UI

Background Controller Variables

Installer Behavior Variables

Storage Backends

SQLite (default)

PostgreSQL (optional)

pgvector (optional)

Environment Variables

Core

Storage

Background Controller

Optional Stack

Optional HTTP Service

MCP

Widening the edit write boundary

Telemetry

Per-Agent Host Setup

Optional Zoekt Backend