Installation

SignalPilot is a Jupyter Lab extension with AI agent capabilities. Install it in under 2 minutes with a single command — no manual setup required.

What You’re Installing

SignalPilot is a Jupyter Lab extension (soon VSCode) that provides:

Agentic Harness

Long-running agent with analyst-in-the-loop approval

Multi-Source Context

Connects to dbt, databases, Slack, Jira, query history via MCP

Memory & Hooks

Institutional knowledge retention + safety guardrails

Skills & Rules

Custom analysis patterns + team coding standards

The SignalPilot Installer: `uvx` CLI

The uvx CLI is a bootstrap installer (not the product itself) that:

Creates your workspace (~/SignalPilotHome)
Installs isolated Python 3.12 + Jupyter Lab + SignalPilot extension
Sets up data science packages (pandas, numpy, matplotlib, plotly)
Launches Jupyter with SignalPilot pre-configured

Product vs Installer: The Jupyter extension is the product. The CLI just installs it in one command.

Quick Install (Recommended)

Prerequisites: macOS, Linux, or Windows (WSL) • Internet connection Don’t have uv? Install it first (takes seconds):

curl -LsSf https://astral.sh/uv/install.sh | sh

Then install SignalPilot:

Run the installer

uvx signalpilot

Expected Output

🚀 SignalPilot Setup
───────────────────────────────────────────────
✓ Creating workspace at ~/SignalPilotHome
✓ Installing Python 3.12 environment
✓ Installing Jupyter Lab + SignalPilot extension
✓ Installing data packages (pandas, numpy, matplotlib, plotly)
✓ Setting up starter notebooks

🎉 Setup complete!

📂 Workspace: ~/SignalPilotHome
🔗 Opening Jupyter Lab at http://localhost:8888

Time: ~2 minutesWhat gets created:

~/SignalPilotHome/
├── data/              # Put local files here for @mentions
├── user-skills/       # Your custom analysis patterns
├── user-rules/        # Your team's coding standards
├── team-workspace/    # Shared notebooks (git-tracked)
├── demo-project/      # Example notebooks
├── start-here.ipynb   # Quick start guide
├── pyproject.toml     # Project config
└── .venv/             # Python environment

Closed terminal or browser? Relaunch anytime

Option 1: Using uvx (recommended)

uvx signalpilot home

Option 2: Manual activation

cd ~/SignalPilotHome
source .venv/bin/activate && jupyter lab

Jupyter Lab opens automatically

Your browser opens at http://localhost:8888You’ll see the SignalPilot panel in the left and right sidebar with:

Chat interface for agent interaction
DB, Folder, MCP connectors and explorers
Plan approval UI (analyst-in-the-loop)
Skills & Rules editor

When creating notebooks, always use the default Python 3 kernel. SignalPilot uses this kernel and may not work with other kernels due to missing system variables.

Start your first investigation

Use local files: Type @ in the chat to mention CSV, Excel, or data files from:

~/SignalPilotHome/data/ (home workspace)
./data/ (current working project directory)

Add more folders: Use the File Scanner in the left sidebar to index additional directories.Or jump to the 5-minute quickstart tutorial.

Launching Jupyter Lab Anytime

Once installed, you can launch Jupyter Lab anytime with:

uvx signalpilot home

What this does:

Opens Jupyter Lab in ~/SignalPilotHome workspace
Uses home environment from ~/SignalPilotHome/.venv
SignalPilot extension is pre-loaded
Opens browser at http://localhost:8888

uvx signalpilot home is shorthand for uvx signalpilot lab --home

Working elsewhere? Use uvx signalpilot lab to open Jupyter in your current directory with the home environment.

Pass custom Jupyter Lab arguments

You can pass any Jupyter Lab flags after the command:

# Custom port
uvx signalpilot home --port=8889

# Disable browser auto-open
uvx signalpilot home --no-browser

# Bind to all network interfaces (access remotely)
uvx signalpilot home --ip=0.0.0.0 --port=9999

All standard jupyter lab arguments work.

Manual Installation Methods

If you can’t use uvx or prefer manual setup with pip, conda, or uv:

Manual with uv
Manual with pip/conda
uv tool install

When to use: Corporate environments, custom Python setup, or full control

Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

Create workspace and install packages

mkdir -p ~/SignalPilotHome && cd ~/SignalPilotHome
uv venv --seed --python 3.12
source .venv/bin/activate
uv pip install signalpilot-ai jupyterlab pandas numpy matplotlib plotly

Launch Jupyter Lab

jupyter lab

Opens at http://localhost:8888

Next time: Just activate and run:

cd ~/SignalPilotHome && source .venv/bin/activate
jupyter lab

When to use: Existing conda workflows, no uv available

Install conda

If not already installed: https://docs.conda.io/en/latest/miniconda.html

Create conda environment

conda create -n signalpilot-env python=3.12

Activate environment

conda activate signalpilot-env

Install packages

mkdir ~/SignalPilotHome && cd ~/SignalPilotHome
pip install signalpilot-ai jupyterlab pandas numpy matplotlib plotly

Launch Jupyter Lab

jupyter lab

Opens at http://localhost:8888

Next time: Just activate and run:

conda activate signalpilot-env
cd ~/SignalPilotHome && jupyter lab

Note: pip/conda is slower than uv (10-100x) and may have dependency conflicts. We recommend uv for best experience.

When to use: Want sp command available globally

uv tool install signalpilot
sp init  # Creates workspace and launches Jupyter

Next time:

sp lab

Working in Different Modes

SignalPilot offers three ways to launch Jupyter Lab:

Default Mode: Current directory + Home environment

cd ~/projects/my-analysis
uvx signalpilot lab

What this does:

Opens Jupyter Lab in your current directory
Uses home environment from ~/SignalPilotHome/.venv
Perfect for quick exploration without setting up new environment

If you have a local .venv with jupyter, you’ll see a red warning prompting you to use --project flag.

Home Mode: SignalPilotHome workspace + Home environment

uvx signalpilot home

What this does:

Opens Jupyter Lab in ~/SignalPilotHome directory
Uses home environment from ~/SignalPilotHome/.venv
Default workspace with all your skills, rules, and team notebooks

Shorthand for uvx signalpilot lab --home

Project Mode: Current directory + Local environment

cd ~/projects/custom-analytics
uvx signalpilot lab --project

What this does:

Opens Jupyter Lab in your current directory
Uses local .venv in that directory (fails if missing)
Great for project-specific work with custom dependencies

Requirements:

A .venv must exist in current directory
Must have jupyterlab and signalpilot-ai installed

Create a project environment:

# Create new project directory
mkdir ~/projects/custom-analytics
cd ~/projects/custom-analytics

# Create Python 3.12 environment
uv venv --seed --python 3.12

# Activate and install dependencies
source .venv/bin/activate
uv pip install jupyterlab signalpilot-ai pandas numpy matplotlib plotly

# Launch SignalPilot
uvx signalpilot lab --project

Keeping SignalPilot Updated

SignalPilot automatically checks for updates when you launch Jupyter Lab. When an update is available, you’ll see a notification: For minor updates:

╭─────────────── 📦 SignalPilot Update ───────────────╮
│ Update Available: 0.11.8 (installed: 0.11.7)        │
│ Run 'uvx signalpilot upgrade' to update             │
╰──────────────────────────────────────────────────────╯

For major updates:

╭─────────────── 📦 SignalPilot Update ───────────────╮
│ Important Update: 0.12.0 (installed: 0.11.7)        │
│ This is a MAJOR update                              │
╰──────────────────────────────────────────────────────╯
Upgrade now? [y/n] (n):

Manual upgrade commands

Upgrade the home environment:

uvx signalpilot upgrade

Upgrade a project’s local environment:

cd /path/to/project
uvx signalpilot upgrade --project

What gets updated:

signalpilot CLI tool
signalpilot-ai Jupyter extension
Core dependencies
Preserves your workspace and configuration

Disable auto-update checks

Update checks happen in the background and never slow down Jupyter startup.To disable them, edit ~/SignalPilotHome/.signalpilot/config.toml:

[updates]
check_for_updates = false

Managing Python Packages

SignalPilot uses uv for fast, reliable package management.

Why uv? 10-100x faster than pip/conda, better dependency resolution, and native integration with SignalPilot kernel.

Add a package

cd ~/SignalPilotHome
uv add scikit-learn  # Adds to pyproject.toml and installs

Remove a package

uv remove scikit-learn

List installed packages

uv pip list

Install from requirements.txt

uv pip install -r requirements.txt

Troubleshooting

Jupyter Lab won't start

Symptoms: Browser doesn’t open or shows connection errorSolutions:

# 1. Check Python version (must be 3.10+)
python --version

# 2. Run diagnostics
sp doctor

# 3. Check if port is already in use
lsof -i :8888  # macOS/Linux

# 4. Try a different port
uvx signalpilot home --port=8889

Still not working? Check troubleshooting guide for detailed solutions.

SignalPilot extension not showing

Symptoms: No SignalPilot panel in Jupyter Lab sidebarSolutions:

# 1. Verify extension is installed
jupyter labextension list | grep signalpilot

# 2. Rebuild Jupyter Lab
cd ~/SignalPilotHome
jupyter lab build

# 3. Clear browser cache and hard refresh
# Chrome/Firefox: Cmd+Shift+R (Mac) or Ctrl+Shift+R (Win/Linux)

Expected output:

signalpilot-ai v1.0.0 enabled OK

MCP server connection failed

Symptoms: “Cannot connect to MCP server” error in chatSolutions:

# 1. Run diagnostics
sp doctor

# 2. Check MCP server status
ps aux | grep mcp

# 3. Restart Jupyter Lab
# Stop (Ctrl+C) and restart
uvx signalpilot lab

Note: MCP servers start automatically with Jupyter Lab. If issues persist, check firewall settings.

Permission denied errors

Symptoms: Cannot create ~/SignalPilotHome directorySolutions:

# 1. Check directory permissions
ls -ld ~/

# 2. Ensure you own the home directory
# (avoid using sudo)

# 3. Use a custom location you own
mkdir ~/my-workspace
cd ~/my-workspace
uvx signalpilot lab --project

Important: Never run SignalPilot with sudo — this can cause permission issues later.

uv not found

Symptoms: uvx: command not foundSolutions:

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Add to PATH (if not auto-added)
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Verify installation
uv --version

Full Troubleshooting Guide

Detailed solutions for installation, networking, and runtime issues

Next Steps

5-Minute Quickstart

Complete your first investigation with real data

Connect a Database

PostgreSQL, Snowflake, BigQuery, Databricks

dbt Integration

Connect dbt Cloud or Core for lineage awareness

Key Concepts

Understand agents, memory, hooks, skills, and rules

Introduction

Getting Started

Integrations

Core Concepts

Installation

Installation

What You’re Installing

Agentic Harness

Multi-Source Context

Memory & Hooks

Skills & Rules

The SignalPilot Installer: `uvx` CLI

Quick Install (Recommended)

Launching Jupyter Lab Anytime

Manual Installation Methods

Working in Different Modes

Default Mode: Current directory + Home environment

Home Mode: SignalPilotHome workspace + Home environment

Project Mode: Current directory + Local environment

Keeping SignalPilot Updated

Managing Python Packages

Add a package

Remove a package

List installed packages

Install from requirements.txt

Troubleshooting

Full Troubleshooting Guide

Next Steps

5-Minute Quickstart

Connect a Database

dbt Integration

Key Concepts

​Installation

​What You’re Installing

Agentic Harness

Multi-Source Context

Memory & Hooks

Skills & Rules

​The SignalPilot Installer: uvx CLI

​Quick Install (Recommended)

​Launching Jupyter Lab Anytime

​Manual Installation Methods

​Working in Different Modes

​Default Mode: Current directory + Home environment

​Home Mode: SignalPilotHome workspace + Home environment

​Project Mode: Current directory + Local environment

​Keeping SignalPilot Updated

​Managing Python Packages

​Add a package

​Remove a package

​List installed packages

​Install from requirements.txt

​Troubleshooting

Full Troubleshooting Guide

​Next Steps

5-Minute Quickstart

Connect a Database

dbt Integration

Key Concepts

Installation

What You’re Installing

The SignalPilot Installer: `uvx` CLI

Quick Install (Recommended)

Launching Jupyter Lab Anytime

Manual Installation Methods

Working in Different Modes

Default Mode: Current directory + Home environment

Home Mode: SignalPilotHome workspace + Home environment

Project Mode: Current directory + Local environment

Keeping SignalPilot Updated

Managing Python Packages

Add a package

Remove a package

List installed packages

Install from requirements.txt

Troubleshooting

Next Steps