> ## Documentation Index
> Fetch the complete documentation index at: https://signalpilot.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Get SignalPilot up and running in under 2 minutes

# Installation

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

## What You're Installing

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

<CardGroup cols={2}>
  <Card title="Agentic Harness" icon="robot">
    Long-running agent with analyst-in-the-loop approval
  </Card>

  <Card title="Multi-Source Context" icon="plug">
    Connects to dbt, databases, Slack, Jira, query history via MCP
  </Card>

  <Card title="Memory & Hooks" icon="brain">
    Institutional knowledge retention + safety guardrails
  </Card>

  <Card title="Skills & Rules" icon="code">
    Custom analysis patterns + team coding standards
  </Card>
</CardGroup>

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

<Warning>
  **Product vs Installer:** The **Jupyter extension is the product**. The CLI just installs it in one command.
</Warning>

## Quick Install (Recommended)

**Prerequisites:** macOS, Linux, or Windows (WSL) • Internet connection

**Don't have [uv](https://docs.astral.sh/uv/getting-started/installation/)?** Install it first (takes seconds):

```bash theme={null}
curl -LsSf https://astral.sh/uv/install.sh | sh
```

<small>Or see [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) for other methods (Homebrew, Windows, etc.)</small>

**Then install SignalPilot:**

<Steps>
  <Step title="Run the installer">
    ```bash theme={null}
    uvx signalpilot
    ```

    <Accordion title="Expected Output" icon="terminal">
      ```
      🚀 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
      ```
    </Accordion>

    **Time:** \~2 minutes

    **What 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
    ```

    <Accordion title="Closed terminal or browser? Relaunch anytime" icon="rotate">
      **Option 1: Using uvx (recommended)**

      ```bash theme={null}
      uvx signalpilot home
      ```

      **Option 2: Manual activation**

      ```bash theme={null}
      cd ~/SignalPilotHome
      source .venv/bin/activate && jupyter lab
      ```
    </Accordion>
  </Step>

  <Step title="Jupyter Lab opens automatically">
    Your browser opens at `http://localhost:8888`

    You'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

    <Warning>
      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.
    </Warning>
  </Step>

  <Step title="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](/docs/getting-started/quickstart).
  </Step>
</Steps>

## Launching Jupyter Lab Anytime

Once installed, you can launch Jupyter Lab anytime with:

```bash theme={null}
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`

<Tip>
  `uvx signalpilot home` is shorthand for `uvx signalpilot lab --home`
</Tip>

<Note>
  **Working elsewhere?** Use `uvx signalpilot lab` to open Jupyter in your current directory with the home environment.
</Note>

<AccordionGroup>
  <Accordion title="Pass custom Jupyter Lab arguments" icon="terminal">
    You can pass any Jupyter Lab flags after the command:

    ```bash theme={null}
    # 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.
  </Accordion>
</AccordionGroup>

## Manual Installation Methods

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

<Tabs>
  <Tab title="Manual with uv">
    **When to use:** Corporate environments, custom Python setup, or full control

    <Steps>
      <Step title="Install uv">
        ```bash theme={null}
        curl -LsSf https://astral.sh/uv/install.sh | sh
        ```
      </Step>

      <Step title="Create workspace and install packages">
        ```bash theme={null}
        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
        ```
      </Step>

      <Step title="Launch Jupyter Lab">
        ```bash theme={null}
        jupyter lab
        ```

        Opens at `http://localhost:8888`
      </Step>
    </Steps>

    **Next time:** Just activate and run:

    ```bash theme={null}
    cd ~/SignalPilotHome && source .venv/bin/activate
    jupyter lab
    ```
  </Tab>

  <Tab title="Manual with pip/conda">
    **When to use:** Existing conda workflows, no uv available

    <Steps>
      <Step title="Install conda">
        If not already installed: [https://docs.conda.io/en/latest/miniconda.html](https://docs.conda.io/en/latest/miniconda.html)
      </Step>

      <Step title="Create conda environment">
        ```bash theme={null}
        conda create -n signalpilot-env python=3.12
        ```
      </Step>

      <Step title="Activate environment">
        ```bash theme={null}
        conda activate signalpilot-env
        ```
      </Step>

      <Step title="Install packages">
        ```bash theme={null}
        mkdir ~/SignalPilotHome && cd ~/SignalPilotHome
        pip install signalpilot-ai jupyterlab pandas numpy matplotlib plotly
        ```
      </Step>

      <Step title="Launch Jupyter Lab">
        ```bash theme={null}
        jupyter lab
        ```

        Opens at `http://localhost:8888`
      </Step>
    </Steps>

    **Next time:** Just activate and run:

    ```bash theme={null}
    conda activate signalpilot-env
    cd ~/SignalPilotHome && jupyter lab
    ```

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

  <Tab title="uv tool install">
    **When to use:** Want `sp` command available globally

    ```bash theme={null}
    uv tool install signalpilot
    sp init  # Creates workspace and launches Jupyter
    ```

    **Next time:**

    ```bash theme={null}
    sp lab
    ```
  </Tab>
</Tabs>

## Working in Different Modes

SignalPilot offers three ways to launch Jupyter Lab:

### Default Mode: Current directory + Home environment

```bash theme={null}
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

<Warning>
  If you have a local `.venv` with jupyter, you'll see a red warning prompting you to use `--project` flag.
</Warning>

### Home Mode: SignalPilotHome workspace + Home environment

```bash theme={null}
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

<Tip>
  Shorthand for `uvx signalpilot lab --home`
</Tip>

### Project Mode: Current directory + Local environment

```bash theme={null}
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:**

```bash theme={null}
# 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):
```

<AccordionGroup>
  <Accordion title="Manual upgrade commands" icon="arrow-up">
    Upgrade the home environment:

    ```bash theme={null}
    uvx signalpilot upgrade
    ```

    Upgrade a project's local environment:

    ```bash theme={null}
    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
  </Accordion>

  <Accordion title="Disable auto-update checks" icon="bell-slash">
    Update checks happen in the background and never slow down Jupyter startup.

    To disable them, edit `~/SignalPilotHome/.signalpilot/config.toml`:

    ```toml theme={null}
    [updates]
    check_for_updates = false
    ```
  </Accordion>
</AccordionGroup>

## Managing Python Packages

SignalPilot uses **uv** for fast, reliable package management.

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

### Add a package

```bash theme={null}
cd ~/SignalPilotHome
uv add scikit-learn  # Adds to pyproject.toml and installs
```

### Remove a package

```bash theme={null}
uv remove scikit-learn
```

### List installed packages

```bash theme={null}
uv pip list
```

### Install from requirements.txt

```bash theme={null}
uv pip install -r requirements.txt
```

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Jupyter Lab won't start" icon="exclamation-circle">
    **Symptoms:** Browser doesn't open or shows connection error

    **Solutions:**

    ```bash theme={null}
    # 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](/docs/reference/troubleshooting) for detailed solutions.
  </Accordion>

  <Accordion title="SignalPilot extension not showing" icon="puzzle-piece">
    **Symptoms:** No SignalPilot panel in Jupyter Lab sidebar

    **Solutions:**

    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="MCP server connection failed" icon="plug">
    **Symptoms:** "Cannot connect to MCP server" error in chat

    **Solutions:**

    ```bash theme={null}
    # 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.
  </Accordion>

  <Accordion title="Permission denied errors" icon="lock">
    **Symptoms:** Cannot create `~/SignalPilotHome` directory

    **Solutions:**

    ```bash theme={null}
    # 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.
  </Accordion>

  <Accordion title="uv not found" icon="question">
    **Symptoms:** `uvx: command not found`

    **Solutions:**

    ```bash theme={null}
    # 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
    ```
  </Accordion>
</AccordionGroup>

<Card title="Full Troubleshooting Guide" icon="wrench" href="/docs/reference/troubleshooting">
  Detailed solutions for installation, networking, and runtime issues
</Card>

## Next Steps

<CardGroup cols={2}>
  <Card title="5-Minute Quickstart" icon="rocket" href="/docs/getting-started/quickstart">
    Complete your first investigation with real data
  </Card>

  <Card title="Connect a Database" icon="database" href="/docs/integrations/databases/postgresql">
    PostgreSQL, Snowflake, BigQuery, Databricks
  </Card>

  <Card title="dbt Integration" icon="diagram-project" href="/docs/integrations/dbt-integration">
    Connect dbt Cloud or Core for lineage awareness
  </Card>

  <Card title="Key Concepts" icon="book" href="/docs/getting-started/key-concepts">
    Understand agents, memory, hooks, skills, and rules
  </Card>
</CardGroup>