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

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:

npm i -g pnpm

Clone and Configure the Repository

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

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:

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, which declares packages under apps/* and packages/*.

Install all dependencies:

pnpm install

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

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.

Run the Electron Desktop Application

Launch the native desktop UI with a single command:

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

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:

docker compose up -d
docker compose logs -f rowboat

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

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 at the repository root.

Configure Optional Features

Google OAuth Integration

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

# 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:

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

Web Search (Brave or Exa)

Create JSON configuration files in the Rowboat config directory:

// ~/.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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}