Quickstart

This guide provides a rapid developer setup for running toorow in a local sandbox environment.

For production container deployments on Google Cloud or custom infrastructure, see the Self-Hosting Guide and Cloud Hosting Architecture.

Prerequisites

Before running the commands below, ensure your local machine has the following tools installed:

Python 3.12
uv package manager
Node.js 22.x or higher
pnpm 9.x (corepack enable)
Docker Desktop with Compose (optional, for local Nango and Postgres)

See the full Prerequisites Guide for detailed service and tool specifications.

1. Clone & Install Dependencies

git clone https://github.com/Toorow/Toorow.git toorow
cd toorow

# Install Python backend packages with uv
uv sync --all-packages --frozen

# Install UI workspace packages with pnpm
pnpm -C ui install --frozen-lockfile
pnpm -C ui build:tokens

2. Environment Configuration

Copy the default environment template:

cp .env.example .env

By default, .env.example configures TOOROW_AUTH_MODE=static with local defaults suitable for offline development.

The Python server process reads environment variables directly upon boot. Updating .env requires restarting the server process.

3. Run the FastMCP Server

Start the local server backend:

uv run --package toorow-server python -m core.main

The FastMCP HTTP endpoint will be available at http://localhost:8000/mcp. To specify a custom port (e.g. PowerShell):

$env:PORT = "8000"
uv run --package toorow-server python -m core.main

4. Run the Admin Console

Start the React Admin Console in development mode with Hot Module Replacement (HMR):

pnpm -C ui --filter @toorow/admin dev

The Vite dev server will launch at http://localhost:5174 and automatically proxy /api requests to the FastMCP backend at http://localhost:8000.

5. (Optional) Launch Local Nango & PostgreSQL Stack

To test OAuth connection flows, multi-project governance, and full database persistence locally:

cp infra/nango/.env.example infra/nango/.env
python -c "import base64,secrets; print(base64.b64encode(secrets.token_bytes(32)).decode())"

Paste the generated key into infra/nango/.env under NANGO_ENCRYPTION_KEY, then start the stack:

docker compose --env-file infra/nango/.env -f infra/nango/docker-compose.yml up -d

6. Verify Installation

Run the automated test suite to confirm your local setup:

# Code quality and unit tests
uv run ruff check server
uv run pytest server/tests -q
pnpm -C ui --filter @toorow/admin test

# Run local analytics loop simulation without cloud credentials
uv run python server/modules/google-analytics/seeds/run_local_loop.py

Next Steps & Cross-References

Prerequisites

Review account requirements and local tooling details.

Self-Hosting Guide

Examine full .env parameters and production container deployment steps.

Security & Constraints

Learn about pre-live security checklists and architectural invariants.

Adding a Connector

Build a custom connector module conforming to platform standards.

Self-Hosted Deployment

Self-Hosted Engineering & Connectors

Prerequisites

1. Clone & Install Dependencies

2. Environment Configuration

3. Run the FastMCP Server

4. Run the Admin Console

5. (Optional) Launch Local Nango & PostgreSQL Stack

6. Verify Installation

Next Steps & Cross-References

Prerequisites

Self-Hosting Guide

Security & Constraints

Adding a Connector

​Prerequisites

​1. Clone & Install Dependencies

​2. Environment Configuration

​3. Run the FastMCP Server

​4. Run the Admin Console

​5. (Optional) Launch Local Nango & PostgreSQL Stack

​6. Verify Installation

​Next Steps & Cross-References

Prerequisites

Self-Hosting Guide

Security & Constraints

Adding a Connector

Prerequisites

1. Clone & Install Dependencies

2. Environment Configuration

3. Run the FastMCP Server

4. Run the Admin Console

5. (Optional) Launch Local Nango & PostgreSQL Stack

6. Verify Installation

Next Steps & Cross-References