Getting started

Installation

System requirements, how to install LoCrew from source, how to add Claude Code, Codex or a model provider, and where LoCrew keeps your data.

LoCrew runs from source. You clone the repository, install its dependencies and start it with one command. There is no .env file to prepare: settings, agents and conversations live in a local SQLite database that LoCrew creates on first launch.

#Requirements

What	Details
Node.js	Version 20 or later, with npm. The project's own CI runs on Node 22.
Operating system	The README says LoCrew is built and exercised on Windows and macOS, and that Linux is configured but has not been run by hand. Automated tests also run on Linux. See platform status.
Screen	The window opens at 1440 × 920 and can be made as small as 1024 × 640.
Something to think with	At least one way to run an agent: Claude Code, OpenAI Codex, or an AI provider (a hosted API key or a local model server such as Ollama). You can install LoCrew first and add one later.

Note

LoCrew itself does not need an account and has no sign-up. The runtimes it drives do: Claude Code and Codex use your own login, and hosted providers need your own API key.

#Install LoCrew

Clone the repository and start the app:

Terminal

git clone https://github.com/locrew-dev/locrew.git
cd locrew
npm install
npm run dev

What each step does:

git clone downloads the source into a folder called locrew.
npm install installs the dependencies. It also runs electron-builder install-app-deps, which compiles the SQLite native module (better-sqlite3) for Electron. This step needs a working C/C++ build toolchain on some systems.
npm run dev starts LoCrew with hot reload. A window opens on the setup guide the first time; see First launch.

How you know it worked: the LoCrew window opens and shows Welcome to LoCrew. on a new workspace.

The repository may not be reachable yet

While the repository is private during testing, the clone URL, the starter flow's request to GitHub, and the in-app Documentation and GitHub links return 404. They work once the repository is public.

#Run the built app instead of the dev server

Terminal

npm run build   # typecheck, then build into out/
npm start       # run the built app in preview mode

npm run package builds an unpacked app into release/. npm run dist builds installers (NSIS for Windows, DMG for macOS, AppImage for Linux), but it is guarded: it refuses to run unless the checkout is a tagged version snapshot with no modified files. No installer has been verified on any platform, and none is signed.

#Add a runtime

An agent needs a runtime to think with. You can add any of these before or after installing.

#Claude Code

Terminal

npm i -g @anthropic-ai/claude-code
claude

Run claude once and sign in. LoCrew uses that login; it never asks for your Anthropic credentials. Claude Code agents are the most thoroughly verified runtime: replies, session resume, workspace tool calls and the write-approval gate are tested against the real CLI.

#OpenAI Codex

The Codex CLI ships with LoCrew's @openai/codex-sdk dependency, so there is nothing separate to install. Sign in from the project directory:

Terminal

npx codex

If LoCrew cannot find the bundled CLI it says so and suggests npm install, or installing it separately with npm i -g @openai/codex. Codex agents are beta: the default automated suite only detects the install, and the opt-in live tests that run real Codex turns have no recorded results.

#A model provider

Hosted APIs (OpenAI, Anthropic, Google Gemini and others), any OpenAI-compatible endpoint, and local model servers (Ollama, LM Studio, vLLM, llama.cpp server) are added inside the app under Settings → AI Providers. See AI providers.

#An external agent (A2A)

An agent that runs somewhere else and speaks the Agent2Agent protocol is added when you create the agent, by its Agent Card address. This is beta. See Runtimes.

#Where your data lives

LoCrew keeps everything in one folder on your computer. The exact path is shown in Settings → About → This installation → Data folder.

Item	Where
Database	`locrew.db` (SQLite) in the data folder: agents, channels, messages, runs, flows and settings.
Images you attach to messages	`attachments/`, one folder per conversation.
Skills used by Claude Code agents	`skill-plugins/`.
API keys and other credentials	Encrypted in the database with your operating system's keychain (DPAPI on Windows, Keychain on macOS, libsecret or KWallet on Linux).

If your computer cannot encrypt credentials, saving a key fails instead of storing it in plain text. More in Local data and privacy.

Back up before downgrading

Database migrations run automatically at every launch and only move forward. An older build opening a newer database runs against a schema it does not know. Back up the data folder before switching to an older version.

#Platform status

Platform	Status in the project's own documents
Windows	Built and exercised. Automated tests run on Windows.
macOS	The README says built and exercised. The onboarding plan notes macOS was not run for that feature. No macOS CI job exists.
Linux	Configured; the README says it has not been run by hand. Unit and end-to-end tests run on Linux in CI. Credential storage needs an unlocked keyring (GNOME Keyring or KWallet).

#Common installation problems

Symptom	Fix
`NODE_MODULE_VERSION` error on startup	The SQLite module was built for the wrong runtime. Run `npm run rebuild`.
Electron starts but no window appears	`ELECTRON_RUN_AS_NODE` is set in your shell, which makes Electron run as plain Node.js. Unset it and start again.
A native error box titled LoCrew failed to start	Startup failed before the window loaded, often because the database could not open or a migration failed. The box shows the reason.
Codex is detected but "not signed in"	The CLI ships with the app, but the login does not. Run `npx codex` from the project directory and sign in.

#Next steps

Quickstart: your first agent and your first multi-agent conversation.
First launch: what the setup guide does.