# Remove a machine

Take a machine off your board when you retire it, give it away, or enrolled it by mistake. Revoking it on the board
cuts its access at once; uninstalling the agent on the computer stops it and clears its files. Do both.

## 1. Revoke it on the board

1. Open **Settings → Machines**.
2. On the machine's card, open the **⋯** menu and choose **Revoke…**. Only owners and admins see this menu.
3. Confirm with **Revoke**.

The machine loses all access at once and takes no more work. Sessions already running on it keep running there until
you stop them. A revoked machine is hidden from the list; turn on **Show revoked** to see it.

Its cards move to another of your machines that has their team's repositories: a card pinned to it, its queued runs
and its pull request's checks and reviews go there, and a card linked to one of its worktrees moves only to a
machine with the same worktree. A machine on the same computer is picked first. A card no other machine can take
waits, its queued run saying **the machine it was sent to is gone**, until one can.

## 2. Stop the agent on the computer

1. Take the `use-andon` skill out of your coding agents first, while the agent can still do it:

   ```sh
   andon policy cli-skill off
   ```

2. Stop the service:

   ```sh
   andon uninstall-service
   ```

   On a Mac this takes the LaunchAgent out of launchd; on Linux it disables and stops the systemd user unit. The service
   file itself stays.

3. End any run sessions still open: `tmux -L andon ls` lists them, and `tmux -L andon kill-server` ends them all. Commit
   or copy anything you want from their worktrees first.

For a second agent on the same computer, put `--profile <name>` before each command
([One machine, several boards](https://andon-docs.pages.dev/machines/multiple-agents.md)).

## 3. Remove its files

Nothing above deletes files. To clear the agent off the computer, move these to the Trash:

| What | Mac | Linux |
|---|---|---|
| Service file | `~/Library/LaunchAgents/dev.andon.agent.plist` | `~/.config/systemd/user/andon-agent.service` |
| The `andon` command | `~/.local/bin/andon` | `~/.local/bin/andon` |
| The agent, its terminal helper and skill | `~/.local/share/andon/` | `~/.local/share/andon/` |
| Config, credential file and host id | `~/.config/andon/` | `~/.config/andon/` |
| Run state, accounts, Codex and Gemini homes | `~/.local/state/andon/` | `~/.local/state/andon/` |
| Logs | `~/Library/Logs/andon/` | the journal (`journalctl --user -u andon-agent.service`) |

Before you move `~/.config/andon/` to the Trash, note the `machineId` in its `config.json`, and remove the machine
credential from the system store with it:

- **Mac:** `security delete-generic-password -s andon-agent -a <machineId>` (or delete that **andon-agent** entry in
  Keychain Access).
- **Linux desktop:** `secret-tool clear service andon-agent account <machineId>`. On a server it was the
  `credentials.json` file in `~/.config/andon/`.

Every agent on the computer stores its credential under the service `andon-agent`, so always name the account: without
it, these commands can remove another board's agent's credential.

Card worktrees live in your projects folder (`~/Projects/worktrees/` unless you changed `projectsRoot`). Move them to
the Trash once you no longer need their branches.

If the machine runs agents for other boards too, keep the folders in the table and `~/.local/bin/andon`: in each folder,
remove only the profile's `profiles/<name>/`, and its service file (`dev.andon.agent.<name>.plist` on a Mac,
`andon-agent-<name>.service` on Linux). Take the profile's `machineId` from `~/.config/andon/profiles/<name>/config.json`.

## Put a machine back

To enroll a revoked machine again, run setup on it and approve it on the board:

```sh
andon setup --url https://<your board>
```

The board installer refuses to run over an existing install, so use `andon setup` while the agent's files are still
there, and the installer once you have removed them.

The machine comes back as a new machine. When it first syncs its repositories, the cards still on the revoked one
move to it: the ones whose team's repositories it has, with the worktrees it finds again at the same path or on the
same branch. Their queued runs go to it, so a review round or CI fix waiting for the old machine starts there.
