Your own server

Connect an Ubuntu server over SSH and Threadrun installs its runner for you. Threads, factories and loops then run there, and keep going while this computer sleeps.

What you need

• An Ubuntu 22.04 or 24.04 server. x86_64 is the tested architecture. arm64 works, but is less tested.
• SSH access as root, or as a user with passwordless sudo.
• A key that already logs in to the server.
• Memory: 2 GB or more is recommended, and 4 GB if you run factories with several agents. Threadrun refuses a server with less than about 350 MB.
• Disk: at least 3 GB free (5 GB if the server needs a swap file). 20 GB is recommended.

You pay your provider directly for the server. Connecting it is free.

Small servers

A server with less than 1.5 GB of memory is small. Threadrun still installs, with a warning:

• It adds a 2 GB swap file if the server has no swap.
• It keeps no spare sandbox ready, and stops idle sandboxes after 2 minutes instead of 10.
• Expect one thread at a time. Factories with parallel agents may run out of memory.

Add a server

1. Go to Settings → Runners and click Add a server. The runner menu's Add my server… does the same.
2. Enter a Name, the Host (an IP address or a domain name), the Port (22 by default) and the User (root by default).
3. Choose an SSH key. Pick SSH defaults to use your ssh agent and ~/.ssh/config, or Browse… to choose a key file.
4. Click Check server. Threadrun runs a read-only check of SSH, administrator access, operating system, architecture, memory, disk, Docker and outbound HTTPS. Each check shows ✓ when it passes, ! for a warning that doesn't stop the install, or ✗ when it blocks it.
5. Read Threadrun will:. This is the full plan. Nothing changes on the server yet.
6. Click Approve and install and watch the progress.
7. When it finishes, click Run threads there.

If a step fails, the message says what to fix. Fix it, then install again. The installer picks up where it stopped.

Threadrun uses your computer's ssh, so your keys never leave this computer. On the first connection, it trusts the server's host key, as ssh does.

SSH keys with a passphrase

Threadrun can't type a passphrase for you. If the check says your key has a passphrase and isn't loaded in ssh-agent, load it once in a terminal.

On macOS:

ssh-add --apple-use-keychain ~/.ssh/threadrun

On Linux:

ssh-add ~/.ssh/threadrun

On Windows, open PowerShell as administrator, start the OpenSSH agent and keep it running after restarts (once), then load your key:

Get-Service ssh-agent | Set-Service -StartupType Automatic; Start-Service ssh-agent
ssh-add $env:USERPROFILE\.ssh\threadrun

On macOS, to load the key automatically after a restart, add this to ~/.ssh/config:

Host 203.0.113.10
  IdentityFile ~/.ssh/threadrun
  AddKeysToAgent yes
  UseKeychain yes

Replace 203.0.113.10 with your server's address and ~/.ssh/threadrun with your key. Then click Check server again.

What the installer changes

• Installs Docker from Docker's apt repository if it's missing.
• Creates a threadrun system user with no password, no login shell and no sudo. It can use Docker only.
• Writes the runner to /opt/threadrun, and its settings to /etc/threadrun/runner.env, readable by root and threadrun only.
• Adds a threadrun systemd service that restarts after a failure and starts on boot.
• Adds a 2 GB swap file (/swapfile) on a small server that has no swap.
• Copies or pulls the runner images.

The installer opens no ports. The runner listens on 127.0.0.1 only. This app reaches it through an SSH tunnel that reconnects when the connection drops. Each server gets its own random access token. It's kept in your keychain and in the server's settings file, and it is never given to sandboxes.

Images

Threadrun copies the runner images from this computer when they match the server's architecture. Otherwise, the server downloads them from GitHub's container registry, ghcr.io. If the packages are private, the app shows how to make them public. A private download uses your GitHub login once, and the login is not stored on the server.

Updating

Updates never interrupt your agents. When an agent is working, the update waits until it finishes, and the server's card says so (for example Update to 0.5.0 waits until your 2 agents finish). The same goes for the runtime on this computer. Restart and Stop are the exception: they act at once, and the card warns you when agents are working.

A server's runner keeps the same version as your app. When the app updates, it updates each server it connects to, without asking. While that happens, the server's card shows Updating…, then a note when it's done. Updating removes earlier runner images, keeps your phone access settings, and doesn't delete threads or their files.

To update a server only when you choose, untick Update the runner automatically when this app updates on its card. The card then shows Update to and the new version available when the runner is behind. Click Update runner (new version), check the plan, and click Approve and update.

An update needs less than 1 GB of free disk, because most of the runner is already on the server. If disk is short, click Clean up first.

Removing a server

Click Remove on the server's card. You get two choices:

• Uninstall and remove removes the runner from the server. That covers the threadrun service, its files and user, every sandbox and its network, phone access, and the swap file if Threadrun added one. Tick Also delete thread data and images on the server to remove the thread volumes and Threadrun's images too. Without the tick, they stay.
• Only forget it in this app leaves the runner running. Threadrun forgets the server, its access token and its threads.

Either way, your server, its SSH access and Docker stay. Your provider keeps billing for the server until you delete it there.

To uninstall by hand, run this on the server:

sudo /opt/threadrun/uninstall.sh

To delete thread data and images too, use sudo TR_PURGE=1 /opt/threadrun/uninstall.sh. Then remove the server in the app with Only forget it in this app.

If a check fails, see Troubleshooting. For how runners work after setup, see Runners.