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

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.