# Quickstart

> The shortest source-backed path from install to a first successful invocation, with the expected output.

- 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`

---

---
title: "Quickstart"
description: "The shortest source-backed path from install to a first successful invocation, with the expected output."
---

Install the macOS desktop app, create a local identity key pair, connect one AI provider, then send the first message in Chef's chat. Lorca is a localhost websocket CLI plus agent loop; the AppKit client is the UI for that CLI and launches the bundled binary.

<Info>
Time: about 10–15 minutes if you already have a supported AI account. Desktop path requires macOS 14 or later.
</Info>

## Prerequisites

| Need | Detail |
| --- | --- |
| Machine | macOS 14+ desktop app (this path). CLI-only setup is covered under [CLI reference](/cli-reference). |
| AI account | One of: DeepSeek, Anthropic, OpenCode Zen, or OpenCode Go API key; or ChatGPT / Grok subscription (SuperGrok or X Premium+) |
| Outcome signal | Chef's chat accepts a message and the bot can answer (provider connected) |

## First successful run (desktop)

<Steps>
<Step title="1. Install the app">
Download Lorca for Mac, open the disk image, and drag Lorca to Applications. The app updates itself; **Check for Updates…** is in the Lorca menu.

For install variants and recovery, see [Installation](/installation).
</Step>

<Step title="2. Create your identity">
On first launch, choose **Create**. Lorca makes a key pair on this computer and shows a **backup phrase**: thirteen groups of four characters.

<Warning>
The backup phrase is your identity. It is the only way to restore your account on another computer, and nobody can reset it for you. Keep it somewhere safe and offline.
</Warning>

Already have an account? Choose **Restore** and type your phrase, or **Pair** and paste a pairing string from another set-up computer (**Pair a Device** in the app, or `lorca pair` in a terminal).
</Step>

<Step title="3. Name your first bot">
Every account starts with one bot, Chef. Keep the name or pick your own.
</Step>

<Step title="4. Connect a provider">
Paste a DeepSeek, Anthropic, OpenCode Zen, or OpenCode Go API key, or sign in to ChatGPT or Grok (browser sign-in). You can skip and connect later in **Settings › Providers**, but bots cannot answer until one provider is connected.
</Step>

<Step title="5. Send the first message">
Open Chef's chat and describe your work. Chef proposes a small team and creates it when you agree.

- **Return** — send
- **`+`** — attach files
- **Microphone** — dictate
</Step>
</Steps>

### Expected result

After step 5:

- Identity exists on this machine (key pair created or restored).
- At least one provider is connected.
- Chef's chat accepts your message; Chef proposes a small team when you describe your work.

If the provider step was skipped, the UI still opens, but bots cannot answer until a provider is connected.

## Local development path (optional)

From a checkout, one command builds the CLI and app, launches the app, and starts a local relay:

```bash
bun run dev          # builds CLI + app, launches app, rebuilds on change; relay on 0.0.0.0:8787
```

Related one-liners from the same surface:

```bash
bun run relay        # local relay on 0.0.0.0:8787 (set LORCA_RELAY_URL to use it)
bun run mobile       # Expo / Metro for the phone app
cargo test           # agent loop, crypto, and SSE tests
bun run reset        # stop everything and wipe identity, credentials, chats, prefs (-y, --build, --relay)
```

<Check>
After `bun run dev`, the desktop app launches and a relay listens on `0.0.0.0:8787`. Point clients with `LORCA_RELAY_URL` when you need that relay.
</Check>

## Phone as a follow-on Device

A phone pairs as a Device (never a Runner): scan a QR from the desktop app or paste a string from `lorca pair`, then talk to the relay with the same keys, envelopes, and jobs as the CLI. Bots keep running on your Runner machines.

```bash
bun run mobile       # Metro for the dev client
bun run mobile:ios   # build and run on the iOS simulator (Xcode)
```

## Recovery notes

| Situation | Action |
| --- | --- |
| New computer, same account | **Restore** with the backup phrase, or **Pair** with a pairing string |
| Pairing string needed | **Pair a Device** in the desktop app, or `lorca pair` |
| Wipe local state (dev) | `bun run reset` (flags: `-y`, `--build`, `--relay`) |
| No bot replies | Connect a provider in **Settings › Providers** |

## Related pages

<CardGroup>
<Card title="Installation" href="/installation">
Prerequisites, install command, first-run success signal, and recovery.
</Card>
<Card title="Overview" href="/overview">
What Lorca exposes: CLI, AppKit client, relay, mobile, and entry points.
</Card>
<Card title="CLI reference" href="/cli-reference">
Commands such as `lorca pair`, flags, and CLI-only setup without the desktop UI.
</Card>
<Card title="Architecture" href="/architecture">
CLI websocket service, agent loop, relay, identity/pairing, and Device vs Runner.
</Card>
</CardGroup>

Next: Open Lorca, confirm a provider under **Settings › Providers**, then send one message in Chef's chat.