# How to Set Up rowboatlabs/rowboat Locally: Complete Installation Guide

> Learn how to set up rowboatlabs/rowboat locally with this complete installation guide. Follow simple steps to clone, install dependencies, build, and launch the UI or web stack.

- Repository: [RowBoat Labs/rowboat](https://github.com/rowboatlabs/rowboat)
- Tags: getting-started
- Published: 2026-02-16

---

**Clone the repository, install pnpm dependencies with `pnpm install`, build shared packages with `npm run deps`, and launch the Electron UI via `npm run dev` or the full web stack via `docker compose up -d`.**

Setting up rowboatlabs/rowboat locally requires understanding its monorepo architecture, which bundles an Electron desktop application, a Next.js web dashboard, and a Python SDK into a single workspace. This guide walks you through installing prerequisites, configuring environment variables, and running each component based on the actual source structure found in `apps/x`, `apps/rowboat`, and `apps/python-sdk`.

## Prerequisites

Before you begin, ensure your system meets these minimum requirements:

| Tool | Minimum Version | Purpose |
|------|----------------|---------|
| **Git** | 2.30+ | Clone the repository |
| **Node.js** | 20.x (LTS) | Run JavaScript applications |
| **pnpm** | 9.x | Workspace package management |
| **Docker & Docker Compose** | 24.x | Run backend services (optional but recommended) |
| **Python** | 3.11+ | Use the Python SDK |

Install pnpm globally if you haven't already:

```bash
npm i -g pnpm

```

## Clone and Configure the Repository

Start by cloning the monorepo and preparing your local environment file.

```bash
git clone https://github.com/rowboatlabs/rowboat.git
cd rowboat

```

Copy the example environment file to `.env` at the repository root and add your API keys:

```bash
cp .env.example .env

# Edit .env to add your OPENAI_API_KEY and optional service keys

```

The only strictly required variable for a minimal run is `OPENAI_API_KEY`. All other entries in `.env` are optional feature toggles for integrations like Google OAuth, Deepgram, or Brave Search.

## Install Dependencies and Build Shared Packages

The workspace is managed by **pnpm** as defined in [`apps/x/pnpm-workspace.yaml`](https://github.com/rowboatlabs/rowboat/blob/main/apps/x/pnpm-workspace.yaml), which declares packages under `apps/*` and `packages/*`.

Install all dependencies:

```bash
pnpm install

```

Before running the Electron application, you must build the shared TypeScript libraries that the renderer and main processes depend on:

```bash
npm run deps

```

This command compiles `@x/shared` and `@x/core` packages located in `apps/x/packages/shared/src/` and `apps/x/packages/core/src/`, then builds the preload script. These compiled outputs are required by the Electron main process entry point at [`apps/x/apps/main/src/main.ts`](https://github.com/rowboatlabs/rowboat/blob/main/apps/x/apps/main/src/main.ts).

## Run the Electron Desktop Application

Launch the native desktop UI with a single command:

```bash
npm run dev

```

This script performs three operations sequentially:

1. **Bundles** shared and core packages using esbuild
2. **Starts** the Vite dev server for the React renderer located in `apps/x/apps/renderer`
3. **Launches** the Electron main process from [`apps/x/apps/main/src/main.ts`](https://github.com/rowboatlabs/rowboat/blob/main/apps/x/apps/main/src/main.ts) once the renderer is available at `http://localhost:5173`

You should see a native desktop window connecting to your local knowledge graph vault.

## Run the Web Dashboard (Next.js)

You can run the web dashboard either directly via Node.js or through Docker Compose for the full backend stack.

### Option A: Direct Node Start (Quick Testing)

Navigate to the Next.js application directory and start the dev server:

```bash
cd apps/rowboat
npm install
npm run dev

```

Access the dashboard at `http://localhost:3000`.

### Option B: Full Stack via Docker Compose (Recommended)

From the repository root, start all backend services including MongoDB, Redis, Qdrant, and the Rowboat API:

```bash
docker compose up -d
docker compose logs -f rowboat

```

To enable optional workers like the RAG worker, use the profiles flag:

```bash
docker compose --profile rag-worker up -d

```

All services read configuration from the `.env` file you created earlier. The Docker Compose configuration is defined in [`docker-compose.yml`](https://github.com/rowboatlabs/rowboat/blob/main/docker-compose.yml) at the repository root.

## Configure Optional Features

### Google OAuth Integration

For Gmail, Calendar, and Drive integration, follow the detailed setup guide:

```bash

# View the guide

open https://github.com/rowboatlabs/rowboat/blob/main/google-setup.md

```

Key steps include creating a Google Cloud project, enabling the required APIs, configuring an OAuth consent screen in testing mode, and creating a UWP OAuth client. Paste the resulting Client ID into the Rowboat UI when prompted during first-run.

### Voice Notes (Deepgram)

Enable local voice transcription by creating a configuration file:

```json
// ~/.rowboat/config/deepgram.json
{
  "apiKey": "<your-deepgram-key>"
}

```

### Web Search (Brave or Exa)

Create JSON configuration files in the Rowboat config directory:

```json
// ~/.rowboat/config/brave-search.json
{
  "apiKey": "<brave-api-key>"
}

// ~/.rowboat/config/exa-search.json
{
  "apiKey": "<exa-api-key>"
}

```

These are automatically loaded when the corresponding feature flags (`USE_BRAVE_SEARCH` or `USE_EXA_SEARCH`) are enabled in your `.env` file.

## Summary

- **rowboatlabs/rowboat** is a monorepo containing an Electron desktop app (`apps/x`), a Next.js web dashboard (`apps/rowboat`), and a Python SDK (`apps/python-sdk`).
- Use **pnpm** to install dependencies and `npm run deps` to build shared TypeScript packages before running the Electron app.
- Launch the desktop UI with `npm run dev` or the full web stack with `docker compose up -d`.
- Configure API keys in `.env` (copied from `.env.example`) and optional features via files in `~/.rowboat/config/`.

## Frequently Asked Questions

### What is the minimum required environment variable to run Rowboat locally?

The only strictly required variable is `OPENAI_API_KEY` in your `.env` file. All other variables for Google OAuth, Deepgram, Brave Search, and Exa are optional and only needed to enable specific integrations.

### Why does the Electron app fail to start with a "module not found" error?

This typically occurs when the shared TypeScript packages haven't been built. Run `npm run deps` from the repository root to compile `@x/shared`, `@x/core`, and the preload scripts that the Electron main process requires before launching `npm run dev`.

### Can I run the web dashboard without Docker?

Yes. Navigate to `apps/rowboat`, run `npm install` to install Next.js dependencies, and start the development server with `npm run dev`. However, you will need to provide your own MongoDB, Redis, and Qdrant instances or configure the application to use external services, as the Docker Compose setup handles these automatically.

### How do I enable the RAG worker for document processing?

Start the Docker Compose stack with the `rag-worker` profile enabled: `docker compose --profile rag-worker up -d`. This launches the optional Node.js service that handles retrieval-augmented generation tasks alongside the core MongoDB, Redis, and Qdrant services.