BotSQUAD
All guides

How to Install BotSQUAD on a VPS: Ubuntu and Docker Guide

Install BotSQUAD on a VPS with Ubuntu or Docker. Connect the server to your account, set up an AI provider, and manage updates, logs and backups.

Installing BotSQUAD on a VPS gives your agents a computer that can stay running when you close your laptop. Their files, conversations and tools live on the server, and you connect from the BotSQUAD app or your browser.

You can install BotSQUAD directly on Ubuntu or run the official Docker image. Both methods connect the server to your BotSQUAD account. Choose one, then follow the same steps to open the server and set up your first agent.

What you need

For the Ubuntu method, use a 64-bit VPS running Ubuntu 24.04 LTS, with systemd and access to sudo. BotSQUAD provides builds for x86_64 and arm64. Ubuntu 24.04 is the baseline used for the full installation tests in the project's documentation.

Have your SSH login details ready, plus access to the email address you use for BotSQUAD. You will also need access to an AI provider when you create an agent. The server installation does not include an AI subscription.

Choose enough RAM and disk space for the work your agents will do. Browser sessions, coding tools and several agents can use more memory than a single text task. Monitor the server as you add work; this guide does not set a universal minimum VPS size.

1. Connect to your VPS

Open a terminal on your computer and connect using the SSH details supplied by your VPS provider:

ssh YOUR_USER@YOUR_VPS_IP

Replace YOUR_USER and YOUR_VPS_IP with your actual login and server address. Run the installation commands below inside that SSH session, on the VPS.

On a fresh Ubuntu server, install the download tools first:

sudo apt-get update
sudo apt-get install -y curl ca-certificates

2. Choose an installation method

MethodWhen to use it
Ubuntu installerYou want BotSQUAD to run as a system service on the VPS.
Docker ComposeYou already manage services with Docker, or prefer to keep BotSQUAD in a container.

Option A: Install directly on Ubuntu

Run the official BotSQUAD server installer:

curl -fsSL \
  https://raw.githubusercontent.com/botsquad/botsquad/main/scripts/install-server.sh |
  sudo bash

The installer downloads the latest released Linux build, verifies its checksum and sets up the BotSQUAD service. On a fresh installation, it creates a separate botsquad service user and starts BotSQUAD in the background.

Sign in and give the server a name you will recognize in the app:

sudo botsquad login --name "BotSQUAD VPS"

Enter the email address for your BotSQUAD account, then the code sent to it. Use the same account when you open the app later.

Check the result:

sudo botsquad status

Look for your installed version, account and server state. If the command cannot reach BotSQUAD yet, check the service log using the troubleshooting section below.

BotSQUAD runs as a system service, so closing the SSH session does not stop it. Continue to step 3.

Option B: Run BotSQUAD with Docker Compose

This option needs Docker Engine and the Docker Compose plugin on the VPS. If they are not installed, follow the Docker installation instructions for Ubuntu first.

Create a new folder for this deployment. Keep its Compose file and security profile together:

mkdir botsquad-vps
cd botsquad-vps
curl -fsSLO \
  https://raw.githubusercontent.com/botsquad/botsquad/main/docker/compose.yaml
curl -fsSLO \
  https://raw.githubusercontent.com/botsquad/botsquad/main/docker/seccomp.json
sudo docker compose up -d

Use another new folder name if botsquad-vps already exists. The official Compose file uses the latest release image and a persistent data volume. It also includes the security profile and shared-memory setting required by the container.

Keep those settings in place. The Electron sandbox stays enabled; the supplied security profile lets it run in the container. Agent commands and files live inside that container, so mount only the host folders you intend agents to use.

Sign in to BotSQUAD and check the server:

sudo docker compose exec botsquad botsquad login --name "BotSQUAD VPS"
sudo docker compose exec botsquad botsquad status

Enter your BotSQUAD account email and its sign-in code. Run later Compose commands from this same deployment folder.

The container uses a persistent volume for its data and restarts according to the Compose policy. Continue to step 3.

3. Open the server in BotSQUAD

Open the BotSQUAD desktop app or BotSQUAD in your browser and sign in to the same account. Find BotSQUAD VPS in the server list and select it.

The standard setup connects through BotSQUAD's existing account and remote-access services. You use the app to reach the VPS; the BotSQUAD container publishes no web port of its own.

When you work on this server, your agents' workspace files and conversations are stored on the VPS. AI providers, websites and connected services can still receive the task data needed for their work.

4. Connect a provider and create an agent

Choose the provider you want to use on the server and follow its sign-in or API-key flow in BotSQUAD. A provider connection on your laptop is not automatically a working connection on the VPS.

If this is a new server with no agents, BotSQUAD offers provider setup before the first-agent form. Once connected, create an agent, give it clear instructions and start with a small task.

For example:

Create a file called server-check.txt in your workspace. Put today's date and a short description of what you can access in it. Do not change system settings or send anything externally.

Open the file in the agent's workspace and check the result. The first-agent guide walks through the agent setup in more detail.

Your VPS can stay available around the clock while its service, network and provider access are working. Check routines and their times before leaving scheduled work running.

Use Hermes Agent on the server

Open the server's provider settings and select Download on the Hermes row. BotSQUAD installs Hermes Agent for its service user, then the row shows Connect.

To install Hermes from a terminal instead, install it as the service user, not as your SSH login. For the Ubuntu installer, run this on the VPS:

sudo -u botsquad -i bash -c \
  'curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --non-interactive'
sudo botsquad restart

For Docker, install it in the container. Hermes stays in the data volume when you replace the container:

sudo docker compose exec botsquad bash -c \
  'curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --non-interactive'
sudo docker compose restart botsquad

Then select Connect on the Hermes row and enter the Nous Portal code. You can also run hermes setup or hermes model as that user to choose another model provider.

5. Read logs and keep the server updated

For the direct Ubuntu installation, these are the main commands:

TaskCommand
Check the serversudo botsquad status
Follow its logssudo botsquad logs -f
Restart BotSQUADsudo botsquad restart
Install the latest updatesudo botsquad update

An update restarts BotSQUAD, so run it when an interruption is acceptable. Back up the server data first. The native service also checks for updates and can stage them for installation; botsquad status shows a staged update.

For Docker Compose, use these commands from your deployment folder:

sudo docker compose logs --tail 100 botsquad
sudo docker compose exec botsquad botsquad status

To upgrade after checking the release notes and making a backup:

sudo docker compose pull
sudo docker compose up -d
sudo docker compose exec botsquad botsquad status

A container upgrade replaces the image and keeps its data volume. The latest tag follows new releases. If you want to choose a specific release, set its version tag in compose.yaml before upgrading. Use the same volume and runtime settings.

BotSQUAD can migrate its database during an upgrade. Use a compatible release with your backup when recovering; switching an upgraded live volume to an older image is not a safe rollback.

Keep a backup of the complete setup

For the native installation with the default service user, keep the service user's home at /var/lib/botsquad and the keyring data at /srv/botsquad-hosted together. If you selected another service user, back up that user's actual home instead.

Stop BotSQUAD before making a consistent copy, then start it again when the copy is complete:

sudo botsquad stop

Back up both locations using your normal backup process, then run:

sudo botsquad start

For Docker, stop the service and back up the complete persistent data volume, then start it again. The volume includes provider sign-ins, the database and its encryption keyring. A copy of the workspace files alone is not a complete backup.

Protect backups like account credentials and keep a copy outside the VPS. A persistent disk or Docker volume can survive a restart, but it is still part of the server you manage.

If the server does not appear

Check that you completed botsquad login on the VPS and that the app uses the same email account. A successful installation alone does not sign the server in.

For the native install, read sudo botsquad status and sudo botsquad logs -f. For Docker, check sudo docker compose ps and the container logs. Follow any reported errors before trying to reinstall.

If the container reports a user-namespace or sandbox problem, check that it uses the official security profile. Some VPS hosts restrict user namespaces or apply extra AppArmor rules. Keep the sandbox enabled and follow the container documentation for those host limits.

If work starts waiting when memory is low, inspect the memory information in botsquad status. Reduce concurrent work or give the VPS more memory for the tasks you want to run.

Frequently asked questions

Will agents keep working when I close my laptop? Yes, while BotSQUAD is running on the VPS and the required services remain available. Your laptop is the client; the VPS runs the agents.

Do I need a domain for this setup? The standard setup uses BotSQUAD's existing account services and app. A custom domain is not required for this installation.

Does the VPS include model access? You connect a provider in BotSQUAD. VPS costs and provider access are separate.

Can I move my existing agents to the VPS? Yes. If you administer both servers, open Transfer in Server settings in the desktop app and choose Copy to another server. Pick the server that has the agents and choose this VPS as the destination. You can copy the agents in one step without handling a file. ZIP import still works. To read a local Hermes folder, use the BotSQUAD desktop app on the computer where the folder is stored.

More guides

AI Agent Workflow: From Task to Finished Result

AI Teammates vs AI Chatbots: When You Need More Than One Conversation

AI Agent Workspace vs Chat History: What Changes in Practice?

How to Import Hermes Agents into BotSQUAD

How to Import Grok Bot Agents into BotSQUAD

20 Real AI Agent Examples for Work and Business

AI Agents vs Agentic AI: What Is the Difference?

Agentic AI Definition: How It Differs From Chatbots

BotSQUAD Hosted Servers: Plans, Pricing, and How They Work

How to Use the BotSQUAD Marketplace: Agents, Skills, and Plugins

What Are AI Agents? How They Work and When to Use Them

What Is BotSQUAD? Models, Providers and Agents Explained

How to Use BotSQUAD: Set Up Your First AI Agent

Meet your first teammate

Run Codex, Claude, Gemini, Grok or your own model with the plans you already pay for, each with its own workspace and context. Your work stays on your computer.

Download BotSQUADContact