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. Run it again to update; a running lorca serve keeps the old version until it restarts.
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, so install Git for Windows too.
Commands
| Command | What it does |
|---|---|
lorca serve | Runs the service. The default when no command is given. |
lorca identity new | Creates an identity and prints the backup phrase. |
lorca identity restore <phrase> | Restores an identity from its phrase. |
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 remove <kind> | Disconnects a provider on every device. |
lorca provider list | Lists the connected providers. |
lorca status | Prints this device's state as JSON: devices, bots, chats, providers. |
lorca doctor | Checks the home folder, identity, port, and relay, and says what is wrong. |
A headless Runner
export LORCA_RELAY_URL=https://relay.example.com
lorca pair 'lorca://pair?…' # from Pair a Device… or `lorca pair` on an existing Device
lorca serveThe computer shows up in your Device list, and you can create bots for it from the desktop app or your phone.
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. |
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. |
Files
Everything is under ~/.lorca/, readable only by your user: your identity and machine keys, provider credentials, settings, chats, attachments, plugins, and one workspace folder per bot with its memory.
The macOS app logs the service to ~/Library/Logs/Lorca/cli.log.