Getting started

Install ChatPilot

What you need, and how to install ChatPilot on a Mac, on Windows or on Linux.

ChatPilot runs on your own computer: a Mac, a Windows PC or a Linux machine (a desktop, a server or Docker). Your messages stay in a database on that computer. iMessage and SMS only work on a Mac; everything else works on all three.

What you need

On a Mac

Install Homebrew if you don't have it, then in Terminal:

brew install uv ffmpeg libmagic node
npm install -g @anthropic-ai/claude-code
claude

In Claude Code, type /login once and sign in with your Claude account, then quit it. Now get ChatPilot itself (replace the address with the one you were given):

git clone <the ChatPilot repository> chatpilot
cd chatpilot
uv sync
uv run chatpilot init

Go on with First start.

On Windows

The easy way: run the install script scripts\install-windows.ps1 from the repository in PowerShell:

powershell -ExecutionPolicy Bypass -File "$HOME\Downloads\install-windows.ps1"

It installs uv, Git and FFmpeg, puts ChatPilot in your user folder (chatpilot), asks for your Telegram user id, your name and the control bot's token, starts ChatPilot in the background and opens the panel. Running it again updates your copy and keeps your settings. Then choose your AI in the panel: Choose the AI.

By hand instead, in PowerShell:

winget install astral-sh.uv Gyan.FFmpeg Git.Git OpenJS.NodeJS
npm install -g @anthropic-ai/claude-code; claude
git clone <the ChatPilot repository> chatpilot; cd chatpilot; uv sync
uv run chatpilot init

(In Claude Code, /login once.) Then go on with First start.

On Linux

Ubuntu or Debian shown; other systems have the same packages under similar names:

sudo apt install ffmpeg libmagic1 git curl
curl -LsSf https://astral.sh/uv/install.sh | sh
npm install -g @anthropic-ai/claude-code && claude
git clone <the ChatPilot repository> chatpilot && cd chatpilot && uv sync
uv run chatpilot init

(In Claude Code, /login once.) Your logins go into the desktop keyring (GNOME Keyring or KWallet). On a server without one, ChatPilot keeps them in a file only your user can read.

A server that runs all the time

ChatPilot can also run on a server, in Docker (docker-compose.yml in the repository):

docker compose up -d
docker compose exec chatpilot chatpilot open

The first start needs no terminal steps: while the control bot isn't set up, ChatPilot shows a small setup page on the panel's address. Open the link the second command prints, paste the bot token from @BotFather and your Telegram user id, and ChatPilot starts. Sign in to the AI from the panel afterwards (Settings → AI → Sign in here).

The panel is then only on the server's own address 127.0.0.1:47821. Reach it from your computer through Tailscale or an SSH tunnel (ssh -L 47821:127.0.0.1:47821 yourserver, then open http://127.0.0.1:47821), or on your own domain over HTTPS: with docker-compose.https.yml next to it, Caddy gets the certificate for you (the steps are at the top of that file). Then the panel asks for your e-mail address, password and authenticator code; set them up once from the link chatpilot open prints. To update, run git pull && docker compose up -d --build in the repository; Settings → Updates says when a new version is out.

Without Docker, on Debian or Ubuntu: sudo scripts/install-server.sh from the repository installs everything ChatPilot needs, runs it as its own chatpilot user, starts it at every boot and keeps your logins in an encrypted file (the key is in /etc/chatpilot/secrets.key; keep a copy). Then sudo chatpilot open prints the link. To update, run the script again with a newer copy. Installed by hand instead, as a service of your own user (next page)? Run sudo loginctl enable-linger $USER so ChatPilot keeps running when you log out.

Where ChatPilot keeps things

Checked against ChatPilot 0.1.0b1. Report a problem with this page