# Host bots on your own server

> Run Neoo Connect on a VPS or homelab with one pairing command, so your bots keep working 24/7 on a machine you control.

A **self-hosted server** is a machine you run (a VPS, a homelab box, a Raspberry Pi) that hosts your bots with Neoo Connect. It works like a Neoo Cloud machine, on your own hardware: bots, routines, webhooks, tables and the knowledge base run there while your computers are off. It shows up in the environment menu as **Your server · name**, and you [move a bot](environments.md#move-a-bot) to it like to any other environment.

> [!WARNING]
> Bots on your server run in **Full Access**: they can read and write files and run commands on that machine, and Neoo does not sandbox them. Run the server in a dedicated container, or under a dedicated user, on a machine that holds no other secrets.

## Add your server

1. Open a bot, click the button next to its message field (**Where this bot runs**) and choose **Add your server**.
2. Type a name (for example *VPS Paris*) and click **Generate command**.
3. Copy the command and run it on your server, within 15 minutes. Choose **Docker** or **Install script**.
4. The dialog shows **Connected** once the server has joined your account. It then appears as **Your server · VPS Paris** in the environment menu.

The pairing token in the command is **single use**, valid for **15 minutes**, and tied to your account. The server creates its own key, joins the Neoo hub, and only then is the token consumed, so a start that failed (no network, container killed) can be retried with the same command until it expires. The token never appears in a URL, and Neoo never writes it in its logs. It is shown once: if you lose it, generate another.

### With Docker

```bash
docker run -d --name neoo-bots --restart unless-stopped \
  -v neoo-bots:/data \
  -e NEOO_PAIR_TOKEN='vpt_…' \
  ghcr.io/vato-group/neoo-connect:latest
```

> [!NOTE]
> The public image `ghcr.io/vato-group/neoo-connect` is **not published yet**. Until it is, build it from the repository (`docker build -f deploy/self-hosted/Dockerfile -t neoo-connect:local .`, then use `neoo-connect:local` in the command) or use the install script. `deploy/self-hosted/docker-compose.yml` is a ready-made example.

The image is based on Node 22, runs as a non-root user, keeps everything (state, provider sign-ins, bot folders) in the `/data` volume, publishes no port, and reports its health to Docker. After the first start the token is no longer needed: you can remove it from your command or compose file.

### With the install script

```bash
curl -fsSL https://api.vatoide.com/api/releases/connect/install.sh | sh -s -- --bot-host --pair 'vpt_…'
```

The script installs Neoo Connect for the current user, pairs it, and installs a user service that starts it at boot. It needs `curl` and `tar`, and no root access. Because the token is on the command line, it is visible to other users of the machine while the script runs and stays in your shell history: it is harmless after 15 minutes or once used, but prefer Docker on a shared machine.

Equivalent manual steps, with the token in the environment instead of the command line:

```bash
NEOO_PAIR_TOKEN='vpt_…' vato-connect pair --name "VPS Paris"
```

`vato-connect start --bot-host` (or `VATO_CONNECT_BOT_HOST=1`) runs the bot host in the foreground.

## Connect your model accounts

A server never receives your provider accounts from your computer. Sign in on the server itself, like on any Connect runner:

```bash
docker exec -it neoo-bots vato-connect accounts add claude
```

Use `codex` or `gemini` for the other providers. The sign-ins stay in the server's volume. A bot can only be moved to the server if its provider is connected there; otherwise the option is greyed out with the reason.

## What's different on your server

| Feature | On your server | On Neoo Cloud |
| --- | --- | --- |
| Always on | Yes: never put to sleep, never woken by Neoo. If the machine is off, its bots can't be reached. | Sleeps after 4 hours, wakes on a message or routine. |
| Models | The accounts you connect on the server (Claude, Codex, Gemini). | Accounts copied from your computer, or Neoo AI. |
| Credits | None: you use your own subscriptions. | Included in the plan. |
| Computer Use | Only if the machine has a desktop session. | Not available. |
| Neoo Vault | Not copied automatically. | Items copied to Neoo Cloud. |
| Routines, webhooks, tables, knowledge base | Yes, same as Neoo Cloud. | Yes. |
| Privacy | End-to-end encrypted between your devices and the server; Neoo only relays messages. | Same. |

## Manage and revoke servers

**Add your server** also lists your servers and their state (waiting, connecting, connected). Click the trash icon next to a server to **revoke** it: its session is closed immediately and it can no longer reach your account. Bots that were on it stay on the machine, but you can't write to them from Neoo anymore. A server can only act for the account that paired it.

If a server stops connecting after you revoked it, or after 30 days, generate a new command and run it again.

## Troubleshooting

- **This server is not paired**: start it with `NEOO_PAIR_TOKEN`, or run `vato-connect pair`.
- **Token refused**: it expired (15 minutes), was already used, or was revoked. Generate a new command.
- **The server never shows as connected**: check that it can reach `https://api.vatoide.com` over HTTPS and WebSocket, then read `docker logs neoo-bots`.
- **Update Neoo on name to move bots there**: the server runs an older Connect. Pull the latest image or rerun the install script.

Source: https://vatoide.com/docs/bots/self-hosted-server