# Alvin Bot on a server, with Docker

For running the bot on a VPS instead of your own machine. Takes about ten
minutes, most of which is the image build.

---

## Before you start

- **A server with Docker.** Any Linux VPS will do; 1 GB RAM is enough, 2 GB is
  comfortable. `docker --version` and `docker compose version` should both
  answer.
- **Node.js on that server**, once, to fetch the templates — or run the fetch on
  your laptop and copy the three files over.
- **A Telegram bot token.** Talk to [@BotFather](https://t.me/BotFather),
  send `/newbot`, keep the token it gives you.
- **Your Telegram user id.** Ask [@userinfobot](https://t.me/userinfobot).
- **One AI provider key.** See the note below — this is where most Docker
  setups go wrong.

### The Agent SDK provider in a container: use a token, not the login

The interactive `claude login` needs a browser, which a container does not
have. Create a long-lived token **once on your own machine** instead and hand
it to the container:

```bash
claude setup-token            # opens the browser, prints a token
```

Then in `.env`:

```bash
PRIMARY_PROVIDER=claude-sdk
CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
```

The agent runtime ships inside the npm package for Linux (x64 and arm64);
nothing else needs installing. An `ANTHROPIC_API_KEY` works the same way.

Without the Agent SDK provider, any of these key-based providers will do:

| Provider | Key from | Notes |
|---|---|---|
| **Groq** | [console.groq.com](https://console.groq.com/keys) | Free tier, no card. Good default. |
| **Google Gemini** | [aistudio.google.com](https://aistudio.google.com/apikey) | Free tier. |
| **OpenAI** | [platform.openai.com](https://platform.openai.com/api-keys) | Paid. |
| **Ollama** | — | Fully local, no key. Needs its own container or a host install. |

---

## Install

```bash
npm install -g alvin-bot        # just to fetch the templates
mkdir -p /opt/alvin-bot && cd /opt/alvin-bot
alvin-bot docker init           # writes Dockerfile, docker-compose.yml, .env
```

Now edit `.env`. The three lines that matter:

```bash
BOT_TOKEN=123456:ABC-your-token
ALLOWED_USERS=123456789         # your Telegram user id
GROQ_API_KEY=gsk_...            # or another provider, see above
```

Then:

```bash
docker compose up -d
docker compose logs -f
```

The first build downloads Chromium and takes a few minutes. You are looking for
`🤖 Alvin Bot started` in the log. Message your bot on Telegram — it should
answer.

---

## Reaching the Web UI

The Web UI is a **full control surface**: it can run shell commands, read files
and spend your API budget. The compose file therefore binds it to loopback, so
it is not reachable from the internet even though the container is running.

**The safe way — an SSH tunnel from your own machine:**

```bash
ssh -N -L 3100:127.0.0.1:3100 root@your-vps
```

Then open <http://127.0.0.1:3100>. Nothing is exposed; the tunnel closes when
you press Ctrl-C.

**If you want it permanently available**, put a reverse proxy with TLS in front
(Caddy, nginx, or Tailscale Serve) and **set `WEB_PASSWORD` in `.env` first**.
The bot refuses its mutating endpoints when it is reachable beyond loopback
without a password — it will still serve the page, but the useful half is
switched off until you set one. That refusal is a backstop, not a security
model: plain HTTP sends that password in the clear.

---

## Everyday operation

```bash
docker compose logs -f            # follow the log
docker compose restart            # restart
docker compose down               # stop (data survives)
docker compose ps                 # status, including health
```

### Updating to a new release

```bash
docker compose build --pull --no-cache
docker compose up -d
```

The image installs `alvin-bot@latest` at build time. To pin a version, set
`ALVIN_VERSION=5.88.0` in `.env` and rebuild.

### Backup

Everything you would miss — sessions, memory, cron jobs, notes, credentials —
lives in the `alvin-data` volume.

```bash
docker run --rm -v alvin-bot_alvin-data:/data -v "$PWD:/out" \
  busybox tar czf /out/alvin-backup-$(date +%F).tar.gz -C /data .
```

Restore into a fresh volume:

```bash
docker run --rm -v alvin-bot_alvin-data:/data -v "$PWD:/in" \
  busybox tar xzf /in/alvin-backup-YYYY-MM-DD.tar.gz -C /data
```

(Check the exact volume name with `docker volume ls` — Compose prefixes it with
the project directory.)

### Time zone

Cron jobs and daily memory files follow the **container's** clock, which is UTC
unless you say otherwise. Set `TZ=Europe/Berlin` (or yours) in `.env` and
restart, or a job you scheduled for 08:00 will fire at a time you did not mean.

---

## When something is wrong

**The container restarts in a loop.**
`docker compose logs --tail 50`. Usually a malformed `.env` — an unquoted `#`
or a stray space around `=`.

**Telegram says nothing.**
Check `ALLOWED_USERS` holds *your* numeric id, not your @handle. The bot
answers nobody else on purpose.

**`"groq" has no API key (GROQ_API_KEY) and is disabled`.**
The bot still comes up — since 5.119.0 a missing key switches off that one
provider, not the engine — and the same line names the provider it started on,
or says plainly that nothing was auto-selected in its place. Set the key the
line names to get your provider back. A line saying
`is not a known provider` means the name itself is wrong: check
`PRIMARY_PROVIDER` for a typo, or for an entry you removed from
`custom-models.json`.

**The Web UI shows the setup wizard.**
That is what an unconfigured install looks like. Fill in `.env` and restart —
the wizard is not the way to configure a container, because what you type there
does not survive a recreate.

**Health shows `unhealthy`.**
The healthcheck asks the Web UI whether it is serving. If the bot is otherwise
alive, check that nothing in `.env` overrode `WEB_HOST` back to `127.0.0.1` —
inside a container that means "unreachable", including for the healthcheck.

**A plugin complains about permissions.**
Report it. Everything the bot writes belongs under `/data`; anything trying to
write into the package directory is a bug on our side.

---

## Windows servers

There is no separate Windows path. Docker on Windows (Server or Desktop) runs
**this same Linux image** through WSL2 — follow the instructions above
unchanged, from PowerShell instead of a shell.

Running the bot natively on Windows without Docker is a different setup and is
covered in [windows.md](windows.md). Note that the automated test suite runs on
macOS and Linux only, so native Windows gets less coverage than either.

---

## What the container does not do

- **No interactive login for the Agent SDK provider** (use the token above).
- **No macOS integrations** — Apple Notes, Shortcuts, the `say` voice. Those
  need a Mac.
- **Browser automation works**, including Chromium — that is what makes the
  image around 700 MB rather than 250.
