Installation

Getting started

Three commands and you’re live — under five minutes from install to running agents.

1. Install the package — one self-contained wheel with the compiled UI and agent gateway bundled in.

   pipx install snippbot

2. Run the setup wizard — opens http://localhost:18781/setup for first-time configuration.

   snippbot setup

3. Start the daemon — launches the daemon and its agent gateway on port 18781.

   snippbot start

---

Prerequisites

Requirement	Minimum	Install
Python	3.11+	python.org
pipx	latest	pipx.pypa.io

Caution

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

Note

No Node.js, pnpm, or build toolchain required — the PyPI package ships with the compiled UI and the agent gateway already bundled.

Install

PyPI (pipx)

Install from PyPI

We recommend pipx, which installs Snippbot into its own isolated environment and puts the snippbot command on your PATH. This works the same on macOS, Linux, and Windows:

pipx install snippbot

Note

On modern macOS (Homebrew) and Debian/Ubuntu, a plain pip install into the system Python is blocked by PEP 668 (externally-managed-environment). pipx sidesteps this. If you prefer pip, install into a virtual environment instead of the system Python:

python3 -m venv ~/.snippbot-venv
~/.snippbot-venv/bin/pip install snippbot

Then run the setup wizard and start the daemon:

snippbot setup       # interactive browser wizard (opens http://localhost:18781/setup)
snippbot start       # start the daemon

What’s included

One pipx install snippbot gives you the full feature set. There are no extras to pick:

Feature	Included
Local voice — speech-to-text (faster-whisper) and text-to-speech (piper)	Yes
Semantic memory recall and search (on-device embeddings, no PyTorch)	Yes
Agent browser tool (Playwright)	Yes. Chromium downloads separately, see below
Gmail tool, web search (DuckDuckGo), image OCR (macOS / Windows)	Yes
Remote-session TOTP, JSONPath hook filters, automatic ngrok tunnel	Yes

The download is about 200–270 MB, depending on the platform. Two large pieces download separately, and only when you ask for them. Snippbot shows exactly what each one installs, with sizes, and asks first:

• Chromium (~280 MB, the browser plus its headless shell) for the browser tool. You don’t need it if you point the browser at your own Chrome.
• Memory visualization pack (scikit-learn + UMAP, ~70–110 MB) for the Memory Nebula map. Agents’ memory recall works without it.

Install either one from Settings → Features. The voice and embedding models download on first use too, and are then cached.

To see which features this install has, open Settings → Features or run snippbot doctor. Optional features covers the in-app installs, the terminal-only extras, and repairing a missing feature.

Platform support

Snippbot installs on macOS, Linux and Windows with Python 3.11–3.14. Everything installs from prebuilt packages, so no compiler is needed. A few features depend on how recent the OS is:

Platform	Local voice + semantic memory	Memory Nebula pack
Apple silicon, macOS 14+	Python 3.11–3.14	Yes
Apple silicon, macOS 13	Python 3.11–3.13	Yes
Apple silicon, macOS 11–12	Python 3.11–3.12	macOS 12 only
Intel Mac, macOS 13+	Python 3.11–3.13	Yes (PCA layout on Python 3.14)
Intel Mac, macOS 11–12	Python 3.11–3.12	Yes
Intel Mac, macOS 10.15	No (the browser tool needs Python 3.11–3.12 here)	Yes
Linux (glibc 2.28+: Ubuntu 20.04+, Debian 10+, RHEL 8+), x86_64 and arm64	Python 3.11–3.14	Yes
Windows 10/11 (x64)	Python 3.11–3.14	Yes

Outside these combinations those features are simply absent; the rest of Snippbot still installs and runs. snippbot doctor shows what applies on your machine. To get them, run Snippbot on a supported Python, for example pipx reinstall --python python3.13 snippbot.

Caution

Linux distributions older than glibc 2.28 (CentOS 7, Ubuntu 18.04) can’t install the voice and embedding libraries, and pip will fail. Use a current distribution.

Optional extras

A few niche features stay opt-in: wallet, ocr (Linux), archives, visualization, embeddings and all. Add one to a pipx install with pipx runpip snippbot install 'snippbot[<extra>]==<version>' (use the version snippbot --version prints). Settings → Features and snippbot doctor show the exact command for your install. See Optional features → Optional extras for what each one adds.

Note

The PyPI package bundles the compiled UI and the agent gateway — no separate Node.js install is required, and the gateway starts automatically alongside the daemon (port 8787).

Docker

Upcoming — not yet supported

Docker deployment is a planned feature and not yet available — the ghcr.io/snippbot/snippbot image is not published. Use the pipx install above for now.

---

Server / VM install

To run Snippbot on a remote server or VM and reach it from other machines, bind to 0.0.0.0 instead of the default 127.0.0.1:

snippbot setup --host 0.0.0.0      # run the wizard bound to all interfaces
snippbot start --host 0.0.0.0      # start the daemon bound to all interfaces

Open ports 18781 (API + UI) and 8787 (agent gateway) in your firewall.

Caution

Binding to 0.0.0.0 exposes the daemon to your network. Put it behind a firewall, VPN, or reverse proxy with TLS — the browser’s microphone and notification APIs only work over https:// or localhost.

---

Setup wizard

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

Step	Name	What it does
1	Genesis	System checks (Python, 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

Manage the daemon with the CLI:

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

snippbot start runs the server in the foreground — it stops when you close the terminal or reboot. To keep it running, register it as a service (next section).

---

Run on startup (managed service)

To start Snippbot on login and restart it automatically if it crashes, install it as a user-level service — no sudo required. One command picks the right mechanism for your OS (systemd on Linux, launchd on macOS, Task Scheduler on Windows):

snippbot service install      # install + start
snippbot service status       # check it
snippbot service uninstall    # stop + remove

Options: --host, --port, and --data-dir are pinned into the unit (e.g. snippbot service install --host 0.0.0.0 to expose it on a network). See snippbot service for details.

Note

pipx install snippbot can’t auto-run this — Python wheels don’t execute post-install code. Run snippbot service install once after installing: pipx install snippbot && snippbot service install.

Headless Linux servers (no logged-in user) want a system service instead, so it runs at boot independent of login. Either run loginctl enable-linger $USER after the command above, or use the installer’s system-unit path: ./scripts/install-vps.sh --service.

---

Uninstall

To remove Snippbot, use the CLI. It stops the daemon (its agent gateway child stops with it), removes the systemd service if one was installed, and prints the final package-removal command:

snippbot uninstall                 # stop daemon + remove service; keep your data
snippbot uninstall --purge         # also delete ALL data in ~/.snippbot (prompts first)
snippbot uninstall --purge --yes   # ...without the confirmation prompt

Your data in ~/.snippbot/ is kept unless you pass --purge. Because a running process can’t reliably delete the environment it’s executing from, uninstall finishes by printing the exact command to remove the package itself (pipx uninstall snippbot or pip uninstall). See setup / doctor / reset / uninstall for details.

---

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
├── logs/                # Daemon + gateway logs
└── backups/             # Automatic backup snapshots

---

Verify it’s running

Open http://localhost:18781 in your browser. You should see the Snippbot dashboard — the compiled UI is served directly from the daemon.

Expand

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 ~/.snippbot/logs/daemon.log    # Check daemon logs
tail -f ~/.snippbot/logs/gateway.log   # Check agent gateway logs
lsof -i :18781                         # Check if the port is in use

Port conflict:

snippbot stop                # Stop the running daemon
snippbot stop --force        # Force kill if it won't stop

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.