# Installation

> Prerequisites, install command, first run, the expected success signal, and one recovery note.

- Repository: egoist/lorca
- GitHub: https://github.com/egoist/lorca
- Human docs: https://grok-wiki.com/public/docs/egoist-lorca-2cf67495e5e6
- Complete Markdown: https://grok-wiki.com/public/docs/egoist-lorca-2cf67495e5e6/llms-full.txt

## Source Files

- `web/content/docs/get-started.mdx`
- `README.md`
- `web/content/docs/cli.mdx`

---

---
title: "Installation"
description: "Prerequisites, install command, first run, the expected success signal, and one recovery note."
---

Install Lorca as the macOS desktop app (bundles the CLI at `Lorca.app/Contents/Resources/bin/lorca`) or as the standalone `lorca` CLI on macOS, Linux, or Windows. The CLI holds keys, talks to the relay and AI providers, and runs bots; a computer running `lorca serve` is a Runner.

## Prerequisites

| Requirement | Detail |
| --- | --- |
| AI account | One API key (DeepSeek, Anthropic, OpenCode Zen, OpenCode Go) or a ChatGPT / Grok subscription (SuperGrok or X Premium+) |
| Desktop app | macOS 14 or later |
| Windows CLI bots | [Git for Windows](https://git-scm.com/downloads/win) — bots run commands in its bash |
| Time | About 5–10 minutes for install + identity |

<Note>
Bots cannot answer until at least one provider is connected. You can skip provider setup at first launch and finish later in **Settings › Providers** or with `lorca provider set`.
</Note>

## Install

<Tabs>
<Tab title="macOS app">

<Steps>
<Step title="Download and place the app">
[Download Lorca for Mac](/download), open the disk image, and drag Lorca to Applications. The app updates itself; use **Check for Updates…** in the Lorca menu.
</Step>
<Step title="Launch">
Open Lorca from Applications. On first launch you create, restore, or pair an identity (next section).
</Step>
</Steps>

</Tab>
<Tab title="CLI (Apple silicon / Linux)">

```bash
curl -fsSL https://lorca.app/install-cli.sh | sh
```

The script downloads the latest release, checks checksums, installs `lorca` to `~/.local/bin`, and adds that folder to your PATH. Run the same command again to update; a running `lorca serve` keeps the old binary until it restarts.

</Tab>
<Tab title="CLI (Windows)">

```powershell
irm https://lorca.app/install-cli.ps1 | iex
```

Same install behavior as the shell script (`~/.local/bin`, PATH update, checksum check). Install Git for Windows before you rely on bot shell commands.

</Tab>
</Tabs>

### Install options (CLI)

| Variable | Effect |
| --- | --- |
| `LORCA_VERSION` | Pin a release (example: `1.0.0`) |
| `LORCA_INSTALL_DIR` | Install directory instead of `~/.local/bin` |
| `LORCA_NO_MODIFY_PATH` | Leave PATH unchanged (`1`) |

<CodeGroup>

```bash title="Pin version (Unix)"
curl -fsSL https://lorca.app/install-cli.sh | LORCA_VERSION=1.0.0 sh
```

```powershell title="Pin version (Windows)"
$env:LORCA_VERSION = '1.0.0'
irm https://lorca.app/install-cli.ps1 | iex
```

</CodeGroup>

## First run

### Desktop app (about 5 minutes)

<Steps>
<Step title="Create identity">
Choose **Create**. Lorca makes a local key pair and shows a **backup phrase**: thirteen groups of four characters.
</Step>
<Step title="Save the phrase offline">
Write the phrase down. It is the only way to restore the account on another computer; nobody can reset it for you.
</Step>
<Step title="Name the first bot">
Every account starts with one bot (default name Chef). Keep it or rename.
</Step>
<Step title="Connect a provider">
Paste an API key, or sign in to ChatGPT or Grok in the browser. Skip only if you will connect later in **Settings › Providers**.
</Step>
</Steps>

Already have an account: choose **Restore** and enter the phrase, or **Pair** with a string from **Pair a Device** / `lorca pair` on a device that is already set up.

### Headless Runner (CLI)

```bash
export LORCA_RELAY_URL=https://relay.example.com
lorca pair 'lorca://pair?…'   # from Pair a Device… or `lorca pair` on an existing Device
lorca serve
```

`lorca serve` is the default when no command is given. The machine appears in your Device list so you can create bots for it from the desktop app or phone.

## Success signal

| Path | What “it worked” looks like |
| --- | --- |
| macOS app | First-run flow finishes; you can open Chef’s chat and send a message after a provider is connected |
| CLI install | `lorca` is on your PATH (unless `LORCA_NO_MODIFY_PATH=1`); `lorca identity show` or `lorca status` runs |
| Headless Runner | After `lorca pair` + `lorca serve`, the computer shows up in the Device list |

Data lives under `~/.lorca/` by default (`LORCA_HOME` overrides). Local websocket port defaults to `4862` (`LORCA_PORT`).

## Recovery

Lost machine, same identity: restore with the backup phrase.

```bash
lorca identity restore <phrase>
```

In the app, choose **Restore** on first launch and type the phrase.

<Tip>
If install or startup looks wrong, run `lorca doctor`. It checks the home folder, identity, port, and relay, and reports what is wrong.
</Tip>

## Related pages

<CardGroup>
<Card title="Quickstart" href="/quickstart">
Shortest path from install to a first successful invocation.
</Card>
<Card title="CLI reference" href="/cli-reference">
Commands, flags, environment variables, and headless Runner setup.
</Card>
<Card title="Configuration reference" href="/configuration-reference">
`LORCA_HOME`, `LORCA_PORT`, `LORCA_RELAY_URL`, model defaults, and where they are read.
</Card>
</CardGroup>

Next: open [Quickstart](/quickstart) and run your first successful invocation (about 2 minutes once installed).