Runners
A runner is the place where your agents work. Threads, factories and loops all run on one. Choose this computer or your own server, switch between them at any time, and manage each one from Settings.
This computer or your server
| This computer | Your server | |
|---|---|---|
| Cost | Free | Free to use; your provider bills the server |
| Keeps running when your laptop sleeps | No | Yes |
| Setup | Docker Desktop | Any Ubuntu server you can reach over SSH |
Model usage is never billed by Threadrun. You pay your agent provider directly, on either runner.
Use a server when work has to finish while you are away. Set one up in Your own server.
Switch runners
Each thread remembers where it runs. You can switch the runner for new work at any time, in three places:
- Runner menu: the badge at the top of the app shows the current runner and its connection, such as This computer · Connected. Click it to choose another runner, or Add my server….
- Run on: the picker in the new thread composer, the factory builder and the loop form. Choosing a runner there switches the app to it, so the new thread, factory or loop starts there.
- Settings → Runners: click Use on a runner's card.
The threads you see are the ones on the runner you are connected to.
What a server card shows
Each server has a card in Settings → Runners:
- Status: Healthy when it runs. Degraded means it runs but has less than 2 GB of free disk. Stopped, Failed (check the logs) and Offline (the app can't reach it) need attention. Not installed means the runner isn't set up yet.
- In use: the runner the app is connected to.
- Machine, Docker, Runner and Sandboxes: what the server has and what is running. The runner version is flagged when it differs from your app's version.
- Phone access: off, or the address the phone pages use.
- Last checked: when the app last looked at the server.
Card actions
| Button | What it does |
|---|---|
| Check | Checks every server again and refreshes its status. |
| Restart | Restarts Threadrun on the server. Threads carry on with their next prompt. |
| Stop | Turns Threadrun off and stops every sandbox. Nothing runs or uses memory until you click Start. Workspaces are kept. |
| Start | Starts Threadrun again after a stop. It replaces Stop while the runner is off. |
| View logs | Shows the runner's most recent log lines on the card. |
| Clean up | Frees disk space and memory. See below. |
| Turn on phone access / Turn off phone access | Turns the phone pages on or off. See Phone access. |
| Install / Update runner | Runs the install steps for a new runner, or for a newer version. Runners update automatically when the app does, unless you untick that on the card. See Your own server. |
| Remove | Uninstalls the runner from the server, or only forgets it in this app. See Your own server. |
Clean up removes earlier runner images, the package download cache and system logs beyond 50 MB. It also turns off multipathd, a storage service, when no multipath device is attached. It then reports how many megabytes it freed. It never touches threads or the current runner.
Threads clean up after themselves
On a server, idle sandboxes are tidied automatically. Times count from a thread's last activity:
- After one minute, the sandbox is paused. It uses no CPU, but keeps its memory, so the next prompt resumes at once.
- After 10 minutes, it is stopped and uses neither CPU nor memory. The next prompt wakes it. On a small server, this happens after 2 minutes.
- After an hour, the workspace is archived to a compressed file, and the container, network and volume are removed. The next prompt restores the workspace into a new sandbox.
Every five minutes, the runner also removes sandbox networks and volumes that no longer have a container.
Why containers, not microVMs
Each sandbox is a Docker container. A microVM is a lightweight virtual machine with its own kernel. It needs hardware virtualisation and reserves about 100 to 200 MB before an agent starts. An idle container uses about 4 MB, and a stopped one uses none. On a small server, that overhead would cost more than the agent itself.
The trade-off: containers share the kernel of the machine they run on. They are not virtual machines.