Skip to content

docs(readme): clarify desktop setup #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
wesbillman merged 1 commit into from
Mar 9, 2026
Merged

docs(readme): clarify desktop setup #4

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 42 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,16 +99,38 @@ append-only and audited.

## Quick Start

**1. Start infrastructure**
**1. Activate the pinned toolchain**

```bash
. ./bin/activate-hermit
```

Hermit pins Rust, Node.js, pnpm, `just`, and related tooling from `bin/`.
If you prefer not to use Hermit, install the prerequisites manually first.

**2. Start infrastructure**

```bash
cp .env.example .env
docker compose up -d
just setup
```

`just setup` starts Docker services and applies pending database migrations.

Services: MySQL `:3306`, Redis `:6379`, Typesense `:8108`, Adminer `:8082`

**2. Start the relay**
**3. Install desktop dependencies**

```bash
just desktop-install
```

This is required before running `just check`, `just ci`, Git hooks, or any
`just desktop-*` command.

The desktop workflow documented here is macOS-first for now.

**4. Start the relay**

```bash
just relay
Expand All @@ -117,7 +139,7 @@ just relay

Relay listens on `ws://localhost:3000` by default.

**3. Mint an API token**
**5. Mint an API token**

```bash
cargo run -p sprout-admin -- mint-token \
Expand All @@ -127,7 +149,7 @@ cargo run -p sprout-admin -- mint-token \

Outputs a bearer token. Set it as `SPROUT_API_TOKEN` for the MCP server.

**4. Connect an agent via MCP**
**6. Connect an agent via MCP**

```bash
SPROUT_RELAY_URL=ws://localhost:3000 \
Expand All @@ -137,6 +159,13 @@ cargo run -p sprout-mcp

The MCP server speaks stdio JSON-RPC. Wire it into any MCP-compatible agent host.

**7. Run the desktop app (optional)**

```bash
just desktop-app
# or: just desktop-dev
```

## Configuration

Copy `.env.example` to `.env`. All defaults work with `docker compose up` out of the box.
Expand Down Expand Up @@ -201,6 +230,14 @@ This repo uses [Hermit](https://cashapp.github.io/hermit/) for toolchain pinning
. ./bin/activate-hermit
```

For a fresh clone, install desktop dependencies before running desktop-aware
checks or hooks:

```bash
just desktop-install
lefthook install
```

**Common tasks**

```bash
Expand Down