Run Companion on a server without Docker

Install Companion on a Debian or Ubuntu server and keep it running as a service. About 5 minutes. The service starts Companion when the server boots and starts it again after a crash.

Install Companion

1. Install Companion, and the virtual display it draws on. A server has no screen, so Companion needs one.

   curl -fsSL https://www.getfounderhq.com/downloads/companion/install.sh | sh
   sudo apt-get install -y xvfb xauth

   The first command ends with a note that this machine has no desktop. That is expected on a server.

2. Create a user for Companion. Do not run Companion as root: the browser engine inside it does not start as root.

   sudo useradd --system --create-home --shell /usr/sbin/nologin companion

Run it as a service

1. Create the service.

   sudo tee /etc/systemd/system/founderhq-companion.service > /dev/null <<'EOF'
   [Unit]
   Description=FounderHQ Companion
   After=network-online.target
   Wants=network-online.target
   
   [Service]
   User=companion
   SyslogIdentifier=founderhq-companion
   ExecStart=/usr/bin/xvfb-run -a -s "-screen 0 1920x1080x24 -nolisten tcp" /usr/bin/founderhq-companion --headless --log-level=3
   Restart=always
   RestartSec=5
   
   [Install]
   WantedBy=multi-user.target
   EOF

2. Start it now, and at every boot.

   sudo systemctl daemon-reload
   sudo systemctl enable --now founderhq-companion

Pair the server

1. Read the log.

   sudo journalctl -u founderhq-companion -f

   The log shows a link and a code between two lines of dashes, under Pair this server with FounderHQ.

2. Open the link in any browser where you are signed in to FounderHQ. Check that the code on the page matches the code in the log, then approve.

3. Press Ctrl+C to leave the log. Companion keeps running: the command only shows the log.

The log says how long the code works. Companion prints a new one after that.

Verify

The log shows Ready for AI requests.

In FounderHQ, open Settings → Companion Apps. The server is in the list and shows Active now.

To check that Companion comes back after a restart, restart the server and run:

systemctl is-active founderhq-companion

It prints active. The server stays paired.

Update

Companion writes a line in the log when a new version is available. Run the install command again, then restart the service.

curl -fsSL https://www.getfounderhq.com/downloads/companion/install.sh | sh
sudo systemctl restart founderhq-companion

Unpair

In FounderHQ, open Settings → Companion Apps, and unpair the server. Companion notices the next time it connects, and prints a new pairing link.

Remove

Unpair the server first. Then stop the service and remove Companion.

sudo systemctl disable --now founderhq-companion
sudo rm /etc/systemd/system/founderhq-companion.service
sudo apt-get remove -y founderhq-companion
sudo userdel --remove companion

The last command deletes the pairing and the caption model, which are in /home/companion/.config/FounderHQ Companion.

See Server settings for the options you can add to the service.

AI agent or LLM? Read this page as markdown