Complete Installation Guide

This guide covers the complete installation process for Tabby AI Keyboard, including all prerequisites, optional features, and advanced configuration.

Looking for a faster setup? Check out the Quick Start guide for essential steps only.

System Requirements

Operating System

Windows 10 or Windows 11

Architecture

x64 (64-bit) processor

RAM

Minimum 8GB (16GB recommended)

Disk Space

At least 5GB free space

Prerequisites

Required Software

Node.js 18+

Download and install from nodejs.orgVerify installation:

node --version  # Should be v18.0.0 or higher

Python 3.12+

Download and install from python.org

Make sure to check “Add Python to PATH” during installation.

Verify installation:

python --version  # Should be 3.12.0 or higher

pnpm Package Manager

Install globally via npm:

npm install -g pnpm

Verify installation:

pnpm --version

uv Python Package Manager

Install from astral.sh/uvOr via pip:

pip install uv

Verify installation:

uv --version

Docker Desktop

Download and install from docker.com

Docker Desktop is required for running the local Supabase instance. Make sure it’s running before starting Tabby.

After installation, start Docker Desktop and verify:

docker --version

API Keys

You’ll need at least one AI provider. OpenAI is recommended for the best experience.

Required

OpenAI API Key - Get it from platform.openai.com/api-keys

Optional AI Providers

Google Generative AI - ai.google.dev
Groq - console.groq.com
Cerebras - cerebras.ai
XAI - x.ai
OpenRouter - openrouter.ai

Additional Services

Tavily API Key - For web search capabilities - tavily.ai
Neo4j Instance - For knowledge graph visualization (optional) - neo4j.com/cloud/platform/aura-graph-database

Installation Steps

1. Clone Repository

git clone https://github.com/CubeStar1/ai-keyboard.git
cd ai-keyboard

2. Install Dependencies

Install dependencies for each component:

Frontend (Electron + Next.js)

cd frontend
pnpm install

This installs:

Electron 38
Next.js 15
React 19
Vercel AI SDK
UI components (Radix UI, Tailwind CSS)

Next.js Backend

cd ../nextjs-backend
pnpm install

This installs:

AI SDK integrations
Supabase client
API route handlers

Memory Backend (Python)

cd ../backend
uv sync

This installs:

FastAPI
Mem0
Supabase vector store
Neo4j connector (optional)

3. Database Setup

Tabby uses a local Supabase instance running in Docker, not the cloud service. This gives you full control and privacy.

Start Docker Desktop

Launch Docker Desktop and wait for it to fully initialize. You should see the Docker icon in your system tray.

Initialize Supabase

From the project root directory:

npx supabase init

This command only needs to be run once. It creates the Supabase configuration directory.

Start Local Supabase

npx supabase start

The first run will download approximately 13 Docker images. This can take 5-10 minutes depending on your internet connection. Subsequent starts take only ~10 seconds.

When complete, you’ll see output similar to:

Started supabase local development setup.

         API URL: http://127.0.0.1:54321
      GraphQL URL: http://127.0.0.1:54321/graphql/v1
   S3 Storage URL: http://127.0.0.1:54321/storage/v1/s3
          DB URL: postgresql://postgres:[email protected]:54322/postgres
      Studio URL: http://127.0.0.1:54323
    Inbucket URL: http://127.0.0.1:54324
        anon key: eyJh...
service_role key: eyJh...
   S3 Access Key: <access-key>
   S3 Secret Key: <secret-key>
      S3 Region: local

Save these credentials - you’ll need them for environment configuration.

Verify Database Schema

The database schema is automatically applied from supabase/migrations/.Verify by visiting Supabase Studio:

http://localhost:54323

Navigate to Table Editor to see the tables.

Create Storage Buckets

Create the required storage buckets for context captures and project assets.

PowerShell
Supabase Studio UI

$headers = @{
  "apikey" = "<SERVICE_ROLE_KEY from step 3>"
  "Authorization" = "Bearer <SERVICE_ROLE_KEY from step 3>"
  "Content-Type" = "application/json"
}

# Create context-captures bucket
Invoke-RestMethod -Uri "http://127.0.0.1:54321/storage/v1/bucket" `
  -Method Post `
  -Headers $headers `
  -Body '{"id":"context-captures","name":"context-captures","public":true}'

# Create project-assets bucket
Invoke-RestMethod -Uri "http://127.0.0.1:54321/storage/v1/bucket" `
  -Method Post `
  -Headers $headers `
  -Body '{"id":"project-assets","name":"project-assets","public":true}'

Open http://localhost:54323
Navigate to Storage
Click “New Bucket”
Create bucket with ID context-captures, set to Public
Create bucket with ID project-assets, set to Public

Supabase Management Commands

Action	Command
Start Supabase	`npx supabase start`
Stop Supabase	`npx supabase stop`
Check Status	`npx supabase status`
Reset Database	`npx supabase db reset`
Open Studio	`http://localhost:54323`

4. Neo4j Setup (Optional)

Neo4j provides knowledge graph visualization for your memories. This is optional but recommended for advanced memory features.

Create Neo4j Instance

Go to Neo4j AuraDB
Sign up for a free account
Create a new free instance

Save Credentials

When creating the instance, Neo4j will provide a credentials file. Download and save it securely.You’ll need:

URI (e.g., neo4j+s://xxxxx.databases.neo4j.io)
Username (usually neo4j)
Password (generated password)
Instance ID
Instance Name

Wait for Instance

Wait for your instance to be fully provisioned (usually takes 1-2 minutes).

5. Environment Configuration

Create and configure environment files for each component.

Create Environment Files

# Frontend
cp frontend/env.example frontend/.env.local

# Next.js Backend
cp nextjs-backend/env.example nextjs-backend/.env.local

# Memory Backend
cp backend/env.example backend/.env

Configure Frontend

Edit frontend/.env.local:

# Supabase (from `npx supabase status`)
NEXT_PUBLIC_SUPABASE_URL="http://127.0.0.1:54321"
NEXT_PUBLIC_SUPABASE_ANON_KEY="<ANON_KEY>"
SUPABASE_ADMIN="<SERVICE_ROLE_KEY>"

# App Configuration
NEXT_PUBLIC_APP_NAME="Tabby"
NEXT_PUBLIC_APP_ICON="/logos/tabby-logo.png"

# Backend URLs
NEXT_PUBLIC_API_URL="http://localhost:3001"
NEXT_PUBLIC_MEMORY_API_URL="http://localhost:8000"

Configure Next.js Backend

Edit nextjs-backend/.env.local:

# Supabase
NEXT_PUBLIC_SUPABASE_URL="http://127.0.0.1:54321"
NEXT_PUBLIC_SUPABASE_ANON_KEY="<ANON_KEY>"
SUPABASE_ADMIN="<SERVICE_ROLE_KEY>"

# Email (optional)
RESEND_API_KEY=""
RESEND_DOMAIN=""

# App Configuration
NEXT_PUBLIC_APP_NAME=Tabby
NEXT_PUBLIC_APP_ICON='/logos/tabby-logo.png'

# AI Providers
OPENAI_API_KEY="your-openai-api-key"
GOOGLE_GENERATIVE_AI_API_KEY=""  # Optional
GROQ_API_KEY=""                   # Optional
CEREBRAS_API_KEY=""               # Optional
OPENROUTER_API_KEY=""             # Optional
XAI_API_KEY=""                    # Optional

# Web Search
TAVILY_API_KEY=""                 # Optional

# Memory Backend
MEMORY_API_URL="http://localhost:8000"

Configure Memory Backend

Edit backend/.env:

# AI Provider
OPENAI_API_KEY="your-openai-api-key"

# Supabase PostgreSQL (from `npx supabase status`)
SUPABASE_CONNECTION_STRING="postgresql://postgres:[email protected]:54322/postgres"

# Neo4j (optional - only if you set up Neo4j)
NEO4J_URL="neo4j+s://xxxxx.databases.neo4j.io"
NEO4J_USERNAME="neo4j"
NEO4J_PASSWORD="your-neo4j-password"

Running Tabby

Make sure Docker Desktop is running before starting the services.

Development Mode

Start all services in separate terminal windows:

Terminal 1: Start Supabase

npx supabase start

Wait for Supabase to fully start before proceeding.

Terminal 2: Start Memory Backend

cd backend
uv run main.py

The memory API will start on http://localhost:8000

Terminal 3: Start Next.js Backend

cd nextjs-backend
pnpm dev

The API backend will start on http://localhost:3001

Terminal 4: Start Windows MCP (Optional)

cd frontend
pnpm run windows-mcp

This provides desktop automation features via MCP. Optional but recommended.

Terminal 5: Start Electron App

cd frontend
pnpm dev

The Electron app will launch with the Next.js frontend on http://localhost:3000

Verify Installation

Check that all services are running:

Service	URL	Description
Supabase Studio	`http://localhost:54323`	Database admin UI
Frontend	`http://localhost:3000`	Main app interface
Next.js Backend	`http://localhost:3001`	API backend
Memory API	`http://localhost:8000`	Memory service
Windows MCP	`http://localhost:8001`	Desktop automation

Building for Production

Local Build

Create a production executable:

cd frontend
npm run dist

The .exe installer will be created in frontend/dist/.

GitHub Releases

For automated releases via GitHub Actions:

Configure GitHub Secrets

Add these secrets to your repository settings:

GH_TOKEN - GitHub Personal Access Token with repo scope
All NEXT_PUBLIC_* variables from .env.local
All SUPABASE_* variables

Trigger Release

cd frontend
npm run release

This will:

Read the version from package.json
Create a Git tag (e.g., v0.1.1)
Push the tag to GitHub
Trigger the GitHub Action
Build the Windows executable
Create a draft GitHub Release

Post-Installation

Access System Tray

After starting the Electron app, look for the Tabby icon in your system tray.Right-click the icon to access:

Show Actions Menu
Brain Panel
Settings
Quit

Configure Settings

Open Settings from the system tray to:

Select your preferred AI model
Configure output mode (Paste/Typewriter)
Customize keyboard shortcuts
Set up custom actions

Learn Shortcuts

Familiarize yourself with the keyboard shortcuts to maximize productivity.

Troubleshooting

Docker Desktop Issues

Problem: Supabase fails to startSolutions:

Ensure Docker Desktop is running
Check available disk space (need at least 5GB)
Verify Docker is not blocked by antivirus/firewall
Try restarting Docker Desktop
Run docker system prune to clean up old images

Port Conflicts

Problem: Services fail because ports are in useCheck ports:

# Windows PowerShell
netstat -ano | findstr :3000
netstat -ano | findstr :3001
netstat -ano | findstr :8000
netstat -ano | findstr :54321

Solutions:

Stop services using those ports
Or modify the ports in configuration files

Python/uv Issues

Problem: Memory backend fails to startSolutions:

Verify Python 3.12+ is installed: python --version
Reinstall uv: pip install --upgrade uv
Delete .venv folder in backend/ and run uv sync again
Check that Supabase connection string is correct

Node.js/pnpm Issues

Problem: Frontend or backend fails to startSolutions:

Verify Node.js 18+: node --version
Clear pnpm cache: pnpm store prune
Delete node_modules and pnpm-lock.yaml, then run pnpm install
Check all environment variables are set

Supabase Storage Issues

Problem: Storage buckets not createdSolutions:

Create buckets manually via Supabase Studio at http://localhost:54323
Ensure service_role key is correct in PowerShell command
Check bucket names are exactly: context-captures and project-assets
Verify buckets are set to “Public”

Neo4j Connection Issues

Problem: Memory service can’t connect to Neo4jSolutions:

Verify Neo4j instance is running in AuraDB dashboard
Check credentials (URI, username, password) are correct
Ensure URI includes neo4j+s:// protocol
Test connection using Neo4j Browser

Next Steps

Configuration Guide

Customize Tabby to match your workflow

Keyboard Shortcuts

Master all shortcuts for maximum productivity

Interview Copilot

Learn to use the coding interview assistant

Memory System

Understand how Tabby remembers and learns

Get Started

Core Concepts

Keyboard Shortcuts

Installation

Complete Installation Guide

System Requirements

Operating System

Architecture

RAM

Disk Space

Prerequisites

Required Software

API Keys

Required

Optional AI Providers

Additional Services

Installation Steps

1. Clone Repository

2. Install Dependencies

3. Database Setup

Supabase Management Commands

4. Neo4j Setup (Optional)

5. Environment Configuration

Running Tabby

Development Mode

Verify Installation

Building for Production

Local Build

GitHub Releases

Post-Installation

Troubleshooting

Next Steps

Configuration Guide

Keyboard Shortcuts

Interview Copilot

Memory System

Build docs developers (and LLMs) love

Get Started

Core Concepts

Keyboard Shortcuts

​Complete Installation Guide

​System Requirements

Operating System

Architecture

RAM

Disk Space

​Prerequisites

​Required Software

​API Keys

​Required

​Optional AI Providers

​Additional Services

​Installation Steps

​1. Clone Repository

​2. Install Dependencies

​3. Database Setup

​Supabase Management Commands

​4. Neo4j Setup (Optional)

​5. Environment Configuration

​Running Tabby

​Development Mode

​Verify Installation

​Building for Production

​Local Build

​GitHub Releases

​Post-Installation

​Troubleshooting

​Next Steps

Configuration Guide

Keyboard Shortcuts

Interview Copilot

Memory System

Build docs developers (and LLMs) love

Complete Installation Guide

System Requirements

Prerequisites

Required Software

API Keys

Required

Optional AI Providers

Additional Services

Installation Steps

1. Clone Repository

2. Install Dependencies

3. Database Setup

Supabase Management Commands

4. Neo4j Setup (Optional)

5. Environment Configuration

Running Tabby

Development Mode

Verify Installation

Building for Production

Local Build

GitHub Releases

Post-Installation

Troubleshooting

Next Steps