Run Companion on a server with Docker

Start Companion on a Linux server that has Docker, and pair it from a link. About 3 minutes. Docker starts it again after a crash or a reboot.

Start Companion

1. Start the container.

   docker run -d --name founderhq-companion --restart unless-stopped \
     -v founderhq-companion:/data ghcr.io/founderhq/founderhq-companion

   • -v founderhq-companion:/data keeps the pairing and the caption model in a volume, so an update does not unpair the server.
   • --restart unless-stopped starts Companion again after a crash and when the server boots.

2. Read the logs.

   docker logs -f founderhq-companion

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

3. 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.

4. 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.

Update

Companion writes a line in the log when a new version is available. Pull the new image and start the container again with the same volume.

docker pull ghcr.io/founderhq/founderhq-companion
docker rm -f founderhq-companion
docker run -d --name founderhq-companion --restart unless-stopped \
  -v founderhq-companion:/data ghcr.io/founderhq/founderhq-companion

The server stays paired.

Unpair

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

You can also unpair from the server:

docker exec founderhq-companion founderhq-companion-headless --unpair

Troubleshoot

"The data folder /data is not writable by this container's user"

You mounted a folder of the server at /data, and it belongs to root. Use a named volume, as in the command above. To keep the folder, give it to the container's user:

sudo chown 1000 /path/to/your/folder

"this container cannot create user namespaces"

This is a note, and Companion works. The browser engine inside Companion isolates the pages it draws, and Docker's default settings do not allow that. Companion then draws them without that isolation. The pages are your FounderHQ pages, and the public pages you ask FounderHQ to read.

See Server settings for the other options.

AI agent or LLM? Read this page as markdown