Installation

Pre-launch — install methods not yet live

Snippbot is in pre-launch. The public GitHub repository, the snippbot PyPI package, and the ghcr.io/snippbot/snippbot Docker image referenced below are not yet publicly available. The instructions on this page describe how install will work once Snippbot ships — they are not actionable today. Follow snippbot.com for launch updates.

Prerequisites

Requirement	Minimum	Install
Python	3.11+	python.org
Node.js	20+	nodejs.org
pnpm	9+	npm install -g pnpm

Caution

Python 3.11 or later is required. Python 3.10 and earlier are not supported.

Install

macOS / Linux

One-command install

Clone the repository and run the install script:

git clone https://github.com/snippbot/snippbot.git
cd snippbot
./INSTALL.sh

The script:

1. Verifies Python 3.11+, Node.js 20+, pnpm
2. Creates a Python virtual environment at .venv/
3. Installs Python packages (core, local, cli)
4. Installs UI dependencies (pnpm install)
5. Starts the dev servers
6. Opens http://localhost:5173/setup in your browser

Options:

./INSTALL.sh --no-browser      # Don't open browser automatically
./INSTALL.sh --fresh           # Wipe all data and start fresh
./INSTALL.sh --new-account     # New account, keep data
./INSTALL.sh --keep-data       # Re-install, keep everything
./INSTALL.sh --vm              # Server install (bind 0.0.0.0)
./INSTALL.sh --vm 10.0.0.5     # Bind to specific IP

Windows

PowerShell install

git clone https://github.com/snippbot/snippbot.git
cd snippbot
.\INSTALL.ps1

Options:

.\INSTALL.ps1 -NoBrowser           # Don't open browser
.\INSTALL.ps1 -Fresh               # Clean install from scratch
.\INSTALL.ps1 -NoCompletions       # Skip shell completions

pip (global)

Install from PyPI

pip install snippbot

Then run the setup wizard:

snippbot setup
snippbot start

Note

The PyPI package includes the compiled UI. No separate Node.js install required.

Docker

Docker Compose

docker-compose.yml

services:
  snippbot:
    image: ghcr.io/snippbot/snippbot:latest
    ports:
      - "18781:18781"
    volumes:
      - snippbot-data:/root/.snippbot
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    restart: unless-stopped

volumes:
  snippbot-data:

docker compose up -d

Then open http://localhost:18781/setup to complete setup.

---

Server / VM install

When installing on a remote server or VM, use --vm to make Snippbot accessible from other machines:

./INSTALL.sh --vm

This binds to 0.0.0.0 instead of 127.0.0.1 and helps configure any firewall to open ports 5173, 18781, and 8787.

---

Setup wizard

After installation, the 8-step setup wizard runs automatically:

Step	Name	What it does
1	Genesis	System checks (Python, Node, ports, disk space, databases)
2	Permissions	Grant microphone and notification access (optional)
3	Identity	Your display name, email, and avatar
4	Account	Create login credentials (username/password or API key)
5	Voice	Configure text-to-speech provider (optional)
6	Model	Select AI provider and enter API keys
7	Marketplace	Install starter packages (optional)
8	Ignition	Verify servers are running, enter the Awakening experience

Tip

You’ll need at least one AI provider API key for the Model step. Snippbot supports Anthropic, OpenAI, Gemini, OpenRouter, DeepSeek, Grok, Groq, and Mistral. The provider list is now sourced from snippbot_core.providers — adding a provider only requires editing that one module.

---

Start and stop

After installation, use START scripts or the CLI to manage servers:

CLI

snippbot start       # Start daemon
snippbot stop        # Stop daemon
snippbot status      # Check status

Script (macOS / Linux)

./START.sh           # Start all servers
./START.sh stop      # Stop all servers
./START.sh status    # Check status
./START.sh restart   # Restart

Script (Windows)

.\START.ps1          # Start all servers
.\START.ps1 stop     # Stop all servers
.\START.ps1 status   # Check status

---

Data directory

All user data is stored in ~/.snippbot/:

~/.snippbot/
├── config.toml          # System config (ports, log level, API keys)
├── setup.json           # Setup wizard state
├── auth.db              # Users, sessions, API keys
├── profile_settings.db  # User profile and preferences
├── snippbot.db          # Main application database
├── avatar.*             # User avatar
└── backups/             # Automatic backup snapshots

---

Verify it’s running

Open http://localhost:5173 in your browser. You should see the Snippbot dashboard.

Expand

Tip

If you installed via pip or Docker (without the dev server), open http://localhost:18781 instead — the compiled UI is served directly from the API server.

You can also verify from the command line:

curl http://localhost:18781/health
# {"status": "ok", "service": "snippbot", "uptime_seconds": 3600.5}

---

Troubleshooting

Server won’t start:

tail -f .logs/backend.log    # Check backend logs
lsof -i :18781               # Check if port is in use

Port conflict:

./START.sh stop              # Stop existing servers
snippbot stop --force        # Force kill

Database issues:

ls -la ~/.snippbot/*.db      # Check databases exist
snippbot doctor              # Run health checks
snippbot reset --soft        # Re-run setup wizard

For more, see Troubleshooting → Common Errors.