Skip to main content

​
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.
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:
1

Run the installer

uvx signalpilot

🚀 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
Option 1: Using uvx (recommended)
uvx signalpilot home
Option 2: Manual activation
cd ~/SignalPilotHome
source .venv/bin/activate && jupyter lab
2

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.
3

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.
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:
When to use: Corporate environments, custom Python setup, or full control
1

Install uv

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

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
3

Launch Jupyter Lab

jupyter lab
Opens at http://localhost:8888
Next time: Just activate and run:
cd ~/SignalPilotHome && source .venv/bin/activate
jupyter 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):
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
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

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