Command line
The lorca CLI holds your keys and runs your bots. The desktop app is a window onto it, and a Runner needs nothing else.
lorca is the program that does the work: it holds your keys, talks to the relay and the AI providers, and runs the bots. It runs on macOS, Linux, and Windows. The desktop app bundles it and runs it for you; on a computer without the app, run the CLI yourself and that computer is a Runner.
On macOS, the bundled binary lives inside the app at Lorca.app/Contents/Resources/bin/lorca.
Install
On an Apple silicon Mac or a Linux computer without the app:
curl -fsSL https://lorca.app/install-cli.sh | shOn Windows, in PowerShell:
irm https://lorca.app/install-cli.ps1 | iexThe script downloads the latest release for your computer, checks it against the release's checksums, puts lorca in ~/.local/bin, and adds that folder to your PATH. From then on lorca updates itself.
Set LORCA_VERSION=1.0.0 to install that release, LORCA_INSTALL_DIR to put lorca in another folder, or LORCA_NO_MODIFY_PATH=1 to leave your PATH alone: curl -fsSL https://lorca.app/install-cli.sh | LORCA_VERSION=1.0.0 sh, or $env:LORCA_VERSION = '1.0.0' before irm in PowerShell.
On Windows, bots run their commands in Git for Windows' bash, not WSL's, so install Git for Windows too. Lorca finds it in Program Files, in an install for your user only, or through git on your PATH; until it is installed, a bot's commands fail with a note that says so.
Commands
| Command | What it does |
|---|---|
lorca | Lists the commands. |
lorca serve | Runs the service. |
lorca identity new | Creates an identity and prints the backup phrase. |
lorca identity restore <phrase> | Restores an identity from its phrase. Without the desktop app, name Lorca's relay: LORCA_RELAY_URL=https://relay.lorca.app lorca identity restore …. |
lorca identity show | Shows this device's identity. |
lorca pair | Shows a pairing string and waits for the other device. |
lorca pair <string> | Joins an account with a pairing string. |
lorca provider set <kind> [api-key] | Connects deepseek, anthropic, opencode, opencode-go, chatgpt, or grok. The key is read from stdin when omitted; --base-url sets a custom endpoint. |
lorca provider add <name> <base-url> | Adds a custom provider: any server that speaks OpenAI's or Anthropic's API, or a decision API for Auto-review. --api picks chat-completions (the default), responses, messages, system-one, or decisions; --model names a model, once per model; --api-key-stdin reads a key. |
lorca provider remove <kind> | Disconnects a provider on every device, or deletes a custom one (custom:openrouter, as provider list shows it). |
lorca provider list | Lists the connected providers. |
lorca mcp … | Manages this computer's own MCP servers; see MCP servers. |
lorca chats list | Lists the chats: each one's id and bots, with a group's owner. |
lorca chats set-owner <group> <bot> | Makes a bot the owner of a group. Name the group by its title or id, and the bot by its name or id. |
lorca tasks list | Lists tasks; --chat-id, --owner-bot-id, and --state narrow it. lorca tasks get <id> shows one. |
lorca tasks create, update, run | Creates, changes, or starts a task from a JSON object, or - to read it from stdin. They need lorca serve running. |
lorca events … | Manages this Runner's event subscriptions and their gateway; see Webhooks and events. |
lorca marketplace reload | Checks lorca.app for a newer marketplace now. Lorca also checks on its own when it starts, when an app connects, and when you or a bot look through the marketplace, at most once an hour, so new plugins and bots arrive without an update. |
lorca models reload | Checks lorca.app for a newer model catalog now. Lorca also checks on its own when it starts and when an app connects, at most once an hour, so new models arrive without an update. |
lorca update | Installs the latest release now. A running lorca serve restarts into it once no bot is working. --check only says whether one is out; --auto off turns automatic updates off, --auto on back on. |
lorca service install | Runs lorca serve in the background, now and at every login, and starts it again if it stops. lorca service uninstall stops it; lorca service status says whether it runs and where its log is. |
lorca status | Prints this device's state as JSON: devices, bots, chats, providers. |
lorca doctor | Checks the home folder, identity, port, relay, and mcp.json, and says what is wrong. |
MCP servers
lorca mcp edits mcp.json in Lorca's folder, the MCP servers every bot on this computer can use. With lorca serve running, the change reaches it at once; without it, the next lorca serve reads the file. After editing the file by hand, run lorca mcp reload.
| Command | What it does |
|---|---|
lorca mcp list | Lists the servers and how each stands: its tools, a sign-in it needs, or why it did not start. Without lorca serve running, it connects each one first. It exits with 1 when a server needs attention. |
lorca mcp get <name> | Connects a server and shows its settings and tools. |
lorca mcp add <name> <command> [args…] | Adds a server this computer runs. Everything after the command is its arguments, flags included; -e KEY=value sets a variable, once per variable, before the command. |
lorca mcp add <name> <url> | Adds a remote server that speaks streamable HTTP. -H "Name: value" adds a header, before or after the URL. |
lorca mcp add-json <name> <json> | Adds a server from its JSON, as a README or another app's config writes it. |
lorca mcp remove <name> | Removes a server, with its sign-in. |
lorca mcp enable <name>, disable <name> | Turns a server on or off. Off, bots don't see it and it never starts. |
lorca mcp sign-in <name> | Signs in to a remote server that asks for it, in this computer's browser. |
lorca mcp sign-out <name> | Forgets a remote server's sign-in. Its next use asks for one again. |
lorca mcp reload | Has the running lorca serve read mcp.json again, after you edit the file by hand. |
lorca mcp hide <name> <tool>, show <name> <tool> | Keeps one of a server's tools from bots, or offers it again. The tool can be a pattern such as delete_*. |
lorca mcp import [file] | Adds the servers from another app's config: Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, or Gemini CLI, or the file you name. |
lorca mcp add notes npx -y @modelcontextprotocol/server-filesystem ~/Notes
lorca mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_… docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
lorca mcp add linear https://mcp.linear.app/mcp
lorca mcp add-json time '{"command": "uvx", "args": ["mcp-server-time"]}'--description tells bots what a server is for, and --timeout how many seconds a call may go without an answer. add connects the server once it is saved and says whether it started.
A headless Runner
lorca pair 'lorca://pair?…' # from Pair a Device… or `lorca pair` on an existing Device
lorca service installThe computer shows up in your Device list, and you can create bots for it from the desktop app or your phone. lorca service install keeps lorca serve running: a launch agent on macOS, a systemd user service on Linux, and a sign-in item on Windows. On Linux it also asks systemd to keep your services running after you log out; if that needs an administrator, it prints the sudo loginctl enable-linger command to run. In a container or anywhere else without systemd, run lorca serve under your own init or in tmux.
Updates
A lorca installed with the script updates itself. lorca serve checks the latest release a few minutes after it starts and then once a day, installs a newer one, and restarts into it once no bot is working, so a turn is never cut off. It installs only a release signed with Lorca's update key, and checks the download against the signed list before it replaces anything. A new release that keeps stopping right after it starts is replaced by the one before.
Settings › Devices shows the version a computer runs. When a newer release is out, Update installs it from any of your devices, so you can update a Runner from your phone. A computer with the desktop app updates with the app instead.
Restarting into a new release on Windows takes lorca service; without it, lorca serve keeps running the old version until you start it again.
Environment
| Variable | What it sets |
|---|---|
LORCA_HOME | Where keys, credentials, and chats live. Default ~/.lorca. |
LORCA_PORT | The local port the app connects to. Default 4862. |
LORCA_RELAY_URL | The relay. A computer that pairs learns it from the pairing code; set it to restore without the desktop app (https://relay.lorca.app), or to use your own relay. |
LORCA_SHELL | The shell bots run commands in. Default /bin/bash; on Windows, Git for Windows' bash. On macOS and Linux, commands get your login shell's PATH and variables either way. |
LORCA_DEEPSEEK_MODEL, LORCA_ANTHROPIC_MODEL, LORCA_CHATGPT_MODEL, LORCA_GROK_MODEL | The default model for bots that do not pick one. |
LORCA_MODELS_FETCH=0, LORCA_MARKETPLACE_FETCH=0 | Turn off the checks for a newer model catalog or marketplace on lorca.app. To serve your own, see Relay. |
Files
Everything is under ~/.lorca/, readable only by your user: your identity and machine keys, provider credentials, settings, chats, attachments, plugins, your MCP servers in mcp.json, the last model catalog fetched in catalog.json, the last marketplace fetched in marketplace.json, the last update check in update.json, the token the apps and lorca send to a running lorca serve in serve-token (a web page cannot reach it), your skills, the secrets bots asked for, the bots' browser profiles, the worktrees and transcripts of coding agents, and one workspace folder per bot with its memory. Skills, secrets, feedback, and the records of tasks, reviews, and projects are encrypted with your account key.
The macOS app logs the service to ~/Library/Logs/Lorca/cli.log. Under lorca service the log is ~/Library/Logs/Lorca/serve.log on macOS, journalctl --user -u lorca on Linux, and serve.log in ~/.lorca on Windows.