# Swarm troubleshooting (for AIs)

The installer is at `/var/lib/swarm-headless/install.sh`; run its commands with `sudo bash`. Below, `install.sh` means that.

| What you see | What to do |
| --- | --- |
| The install stops with "run it with curl ... \| sudo bash" | It was run with `sh` or without root. Run `curl -fsSL https://swarmagent.dev/install \| sudo bash`. |
| Not Ubuntu 24.04 x86_64 | Swarm needs Ubuntu 24.04 on x86_64 (a VM works). Tell the person. |
| `401`, "invalid or missing" key | Swarm was reinstalled or the key was replaced. `install.sh connect-ai --for-user $USER`, then reconnect your MCP client. |
| MCP tools not visible in this session | Use the HTTP calls in https://swarmagent.dev/llms.txt step 3; the MCP server loads in your next session. |
| No provider ready | https://swarmagent.dev/llms.txt step 4 (ask which they have: ChatGPT plan, Claude plan or an API key). |
| Sign-in code expired | Start a new one (`swarm_connect_chatgpt` action start) and give it to the person at once. |
| `workspace_not_visible` | `install.sh workspace add /path --for-user $USER`, then retry. |
| A job failed | `swarm_get_job` shows why. Fix the brief, or the folder's environment (`swarm_set_environment`), and give it again. |
| Job needs input | `swarm_answer_job` with the answer. |
| Deliver refused | A conflict: ask the worker to rebase with `swarm_message_job`; or the job committed nothing. |
| `swarm_status` degraded: a sandbox the person turned on is not active | `install.sh check-sandbox`; `install.sh check-isolation`. (Sandbox off is the default and not degraded.) |
| "environments are off on this machine" | The folder has an environment but Docker is not set up. The person runs `sudo bash /var/lib/swarm-headless/install.sh environments on` (installs Docker and gVisor, a few minutes). |
| Spending over the limit | `swarm_get_usage`; the person raises limits on the machine. |
| Services down | `install.sh status`; `install.sh up` starts them. |
| Update | `install.sh update` downloads the newest release and switches when no job runs, going back if it does not come up. `install.sh auto-update on` for automatic updates. |