tThreadrun Download

Troubleshooting

This page covers the problems you are most likely to meet, and what to do about each one. Each section starts with what you see in the app.

Docker isn't running or isn't installed

You see Docker is installed but not running. or install steps in the Docker step. The runtime waits until Docker runs.

  • If Docker is installed, press Start Docker. Wait for Docker Desktop to finish starting. Threadrun checks on its own and moves on once Docker answers.
  • If Docker isn't installed, follow the steps in Install, then press I've installed it.
  • If Docker Desktop doesn't start, open it yourself once and accept its terms.

Start runtime fails

You see a red error under Start runtime, such as "Couldn't download" or "Couldn't start the runtime".

  • Check your internet connection. The first start downloads the images.
  • Check that Docker is still running.
  • Press Start runtime again. Retrying is safe.

The runtime was started with a different token

You see "The runtime on this computer was started with a different token."

Press Restart runtime. Your threads stay, because they live in the same data volume.

Pressing Enter shows a "Connect … first" notice

The notice names the agent, for example Connect claude-code first. Claude Code and Codex need a sign-in or an API key. Connect the agent in Settings → Accounts, as described in the Quickstart. Or switch the Harness to OpenCode, which works without an account.

A server is offline

You see … is offline with a reason, or Check server reports that a key "has a passphrase and isn't loaded in ssh-agent". The app can't type a passphrase, so load the key once in a terminal:

# macOS: also saves the passphrase in your Keychain
ssh-add --apple-use-keychain ~/.ssh/threadrun

# Linux
ssh-add ~/.ssh/threadrun
# Windows (PowerShell as administrator, once): start the OpenSSH agent and keep it running
Get-Service ssh-agent | Set-Service -StartupType Automatic; Start-Service ssh-agent
ssh-add $env:USERPROFILE\.ssh\threadrun

Then press Check server again. Replace ~/.ssh/threadrun with your key.

If the check says "Permission denied", check the user and the key. Setup needs root or a user with passwordless sudo. See Your server.

Blocked by your network policy

You see the warning Blocked by your network policy. The agent tried to reach a site your egress policy doesn't allow.

  • Admins: press Allow next to the site. Threadrun adds it to the allowed domains. Other roles see the buttons disabled. Ask an admin.
  • Reading a website: an agent can search the web, but it can read a page only if the page's site is allowed. Add the site, for example wttr.in for weather.
  • Web search with OpenCode: the search runs through exa.ai. Open Settings → Governance, check Only allow these domains, then check Web search. Press Save policy.

Read more in Governance.

An MCP server needs an API key

You see Needs API key on Settings → Skills & MCP. Or the thread's Activity says the server "needs authentication".

  1. Open Settings → Skills & MCP and find the server.
  2. Paste the header from the provider's docs, for example x-api-key: your-key.
  3. Press Save key.

The key stays in your keychain. It is sent only to threads that use this server.

If the server comes from your Claude Code, Codex or OpenCode config, you can't add the key here. Add it in that tool's config, then reopen the page.

Free usage limit reached

On OpenCode, the thread shows The model returned an error with a message such as "Free usage limit reached". Free models have usage limits.

  • Choose another model for this thread in the Model picker.
  • Or connect a provider in Settings → Accounts, under OpenCode accounts.

A small server runs out of memory

Servers with less than 1.5 GB of memory show This server is very small during setup. Agents run slowly there, and the system can stop them when memory runs out.

  • Run one thread at a time, and avoid factories with parallel agents.
  • The installer adds a 2 GB swap file if the server has none.
  • For steady work, use a server with 2 GB of memory or more. The setup check suggests 4 GB.

A server shows Degraded: low disk space

The server's card shows Degraded with "low disk space". This means less than 2 GB of disk is free.

Press Clean up on the server's card. It removes earlier versions, caches and old logs. It doesn't delete threads or their files. The setup check recommends 20 GB of free disk.

A thread seems stuck

Start by checking what the thread shows.

  • Working… with a spinner means the agent is still running. Long tasks take time. Press Activity to see the latest steps.
  • If a turn has no activity for 15 minutes, Threadrun cancels it. The Activity log says "No activity … the turn was cancelled". Send your message again.
  • To end a turn now, press Stop. It replaces Send while the agent runs.

An idle thread isn't stuck. Threadrun pauses and then stops idle sandboxes to save memory. Your next message wakes the thread, and the first reply takes a moment longer.