# Files on a machine

Andon puts files on a computer from four places: the board's installer (`install.sh`), the desktop app, `andon up`
and the agent itself. This page lists every one of them, who writes it, who reads it, and which one wins when two
could apply. Read it when `andon` says something you don't expect, before you move a folder to the Trash, or when a
computer has both the desktop app and an installer-installed agent.

The paths are for macOS and Linux. On Windows the agent runs in WSL2, so the Linux paths apply inside it
([Windows machines](https://andon-docs.pages.dev/machines/windows.md)).

## Which config folder `andon` reads

Every `andon` command reads one config folder, chosen in this order:

1. `ANDON_CONFIG_DIR`, when it is set.
2. Otherwise `~/.config/andon`.

A second agent on the computer (a profile, [One machine, several boards](https://andon-docs.pages.dev/machines/multiple-agents.md)) uses
`<that folder>/profiles/<name>/`, picked with `andon --profile <name> …` or `ANDON_PROFILE=<name>`.

The folder each way of running the agent uses:

| Started by | Config folder |
|---|---|
| The installer's `andon` command, and the service it installs | `~/.config/andon` |
| The desktop app's `andon` command | `~/.andon/agent` (the launcher sets `ANDON_CONFIG_DIR` unless your shell already has it) |
| `andon up`, from the desktop app or a checkout's `pnpm andon:up` | `~/.andon/agent` |
| `andon setup` run with `ANDON_CONFIG_DIR` set | that folder; setup writes it into the service file too |

`andon doctor` prints the folder it read on its first line: `✓ config at <path>/config.json`, or `✗` when there is no
config there.

## The two `andon` commands

Both the installer and the desktop app put a launcher at `~/.local/bin/andon`. Only one file fits there, and the two
behave differently.

| | The installer's | The desktop app's |
|---|---|---|
| Second line of the file | `# andon: the Andon machine agent. …` (older installs have no comment, only an `exec` line) | `# andon: written by the Andon app …` |
| Runs | the agent in `~/.local/share/andon/andon.mjs` (or a profile's own copy) with your `node` | the agent inside the app, with the app's own Node |
| Config folder | `~/.config/andon` | `~/.andon/agent` |
| Updates | `andon update` (a signed build from your board) | update the app; `andon update` is refused with "This andon comes with the Andon app: updating the app updates it." |
| Removed with | moving the file to the Trash | **Preferences → The `andon` command → Remove** |

To see which one you have:

```sh
command -v andon
head -3 ~/.local/bin/andon
```

The app only ever writes over its own launcher. When an `andon` without its marker line is already there, the app
leaves it alone, and Preferences says "Installed by the installer in ~/.local/bin/andon … The app leaves it as it is."
That file belongs to an agent the installer set up for `~/.config/andon`, and replacing it would point your terminal
at a different agent. The app also rewrites its own
launcher each time it starts, so it follows the app to a new version or a new folder.

The installer's `andon update` rewrites the installer's launcher when it is out of date, and never a file it didn't
write.

## Every file and folder

"Safe to delete" means you can move it to the Trash without breaking anything that still runs. Stop the agent
first for anything marked "with the agent" ([Remove a machine](https://andon-docs.pages.dev/machines/remove-a-machine.md)).

### The installer and the agent it installs

| Path | Written by | Read by | Holds | Safe to delete |
|---|---|---|---|---|
| `~/.local/bin/andon` | installer; `andon update` refreshes it | your shell | the launcher above | with the agent |
| `~/.local/share/andon/andon.mjs` | installer; `andon update` | the launcher, the service | the agent | with the agent |
| `~/.local/share/andon/update-key.pub` | installer (its default key, or `--update-key`) | `andon update`, self-updates | the release key updates must be signed with | with the agent; without it, signed updates are refused |
| `~/.local/share/andon/prebuilds/` | installer | the agent | the terminal helper (node-pty) for this platform | with the agent |
| `~/.local/share/andon/profiles/<name>/` | `andon --profile <name> setup` | the launcher, that profile's service | a second agent's own copy of the agent | with that profile |
| `~/.config/andon/config.json` | `andon setup`, then the agent and its commands | every `andon` command, the agent | the enrollment, settings, the hook token, the saved capture and API tokens; mode 0600 | no: it is the enrollment |
| `~/.config/andon/credentials.json` | `andon setup` with the file credential backend | the agent | the machine's sign-in; mode 0600. Macs keep it in the Keychain instead, and Linux desktops with a session bus in the Secret Service | no, while the machine is enrolled |
| `~/.config/andon/provider-keys.json` | `andon providers` with the file backend | the agent | API keys for model providers; mode 0600 | only if you add the keys again |
| `~/.config/andon/host-id` | the first agent to start | every agent on the computer | a random id the board uses to tell this computer from others | not while any agent on the computer, the app's included, is enrolled: the next one to start makes a new id, and the board takes it for a different computer |
| `~/.config/andon/profiles/<name>/` | `andon --profile <name> setup` | that profile's commands and agent | a second agent's `config.json` and credentials | with that profile |
| `~/.local/state/andon/` (`stateDir`) | the agent | the agent | run state, harnesses, `accounts/<provider>-<id>/` for each extra account, self-update state | with the agent |
| `~/.local/share/andon/skills/use-andon/` | the agent | Claude Code, Codex and other coding agents, through links | the [use-andon skill](https://andon-docs.pages.dev/machines/use-andon-skill.md) | turn it off instead: `andon policy cli-skill off` |
| `~/.claude/skills/use-andon`, `~/.agents/skills/use-andon` and the other skill folders | the agent | each coding agent | links to the folder above | turn it off instead, as above |
| `~/Library/LaunchAgents/dev.andon.agent.plist` (Mac) | `andon setup`, `andon install-service` | launchd | the service, with any `ANDON_CONFIG_DIR` and `ANDON_PROFILE` it was set up with | after `andon uninstall-service` |
| `~/.config/systemd/user/andon-agent.service` (Linux) | the same | systemd | the same | after `andon uninstall-service` |
| `~/Library/Logs/andon/agent.log`, `agent.err.log` (Mac) | launchd, from the agent's output | you | the service's log | yes |

On Linux the service logs to the journal: `journalctl --user -u andon-agent.service`. A profile's service file is
`dev.andon.agent.<name>.plist` or `andon-agent-<name>.service`, and its state and logs sit under `profiles/<name>/`
in the folders above.

### The desktop app and `andon up`

`andon up` keeps everything in `~/.andon/` (`ANDON_UP_HOME` moves it to `$ANDON_UP_HOME/.andon`). The desktop app runs
`andon up`, so a checkout's `pnpm andon:up` and the app share this folder.

| Path | Written by | Read by | Holds | Safe to delete |
|---|---|---|---|---|
| `~/.andon/env` | `andon up`, on its first run | the server | `ANDON_SECRET_KEY`: sign-ins, stored secrets and signed file links come from it; mode 0600 | no: without it, sign-ins and stored secrets stop working. Keep it with the data |
| `~/.andon/pg/`, `pg.json`, `pg.log` | `andon up` | the Postgres it starts | the database | no: it is your board |
| `~/.andon/storage/` | the server | the server | the board's stored files | no |
| `~/.andon/mail.log` | the server | you | emails it would have sent (invites, sign-in links) | yes |
| `~/.andon/server.log`, `server.pid`, `agent.log`, `agent.pid` | `andon up` | `andon up`, the app | logs, and which processes are its own | the logs, yes; the pid files, not while it runs |
| `~/.andon/server.build`, `board.build` | `andon up` | `andon up`, the app | which build of the server and board is running | yes, while it is stopped |
| `~/.andon/agent/` | `andon up`, when it enrolls this computer | the app's agent and the app's `andon` command | that agent's `config.json`, `credentials.json` (always the file backend) and `state/` | no, while that machine is enrolled |
| `~/.andon/login.log` (Mac) | the login item | you | the output of a start at login | yes |
| `~/Library/LaunchAgents/app.andon.local.plist` (Mac) | the app, when **Start it when you log in** is on | launchd | the login item that runs `andon up` | turn the setting off instead |
| `~/.local/bin/andon` | the app (**Preferences → The `andon` command**) | your shell | the app's launcher | remove it in Preferences |
| `~/Library/Application Support/app.andon.desktop/instances.json` (Mac), `~/.config/app.andon.desktop/instances.json` (Linux) | the app | the app | the instances you added, their order, and the app's preferences | only to start the app from scratch |

`andon up --reset` renames `storage/` and `agent/` aside (`<name>.before-reset-<time>`) instead of deleting them.

The agent `andon up` starts writes `~/.config/andon/host-id` and the use-andon skill folder like any other agent,
so a computer that only ever ran the app still has a `~/.config/andon/` folder, holding only `host-id`.

### Capture scripts

| Path | Written by | Read by | Holds | Safe to delete |
|---|---|---|---|---|
| `~/.config/andon/capture.env` | you, by hand ([Capture from anywhere](https://andon-docs.pages.dev/guide/capture.md)) | `scripts/capture/andon-capture.sh` and `andon-screenshot.sh` only | `ANDON_CAPTURE_URL` and `ANDON_CAPTURE_TOKEN` for those scripts | yes, if you don't use the scripts |

`ANDON_CAPTURE_ENV` points the scripts at another file. The agent never reads `capture.env`: `andon add` uses the
capture token saved with `andon capture-token`.

## Which one wins

| When both exist | The one used |
|---|---|
| `ANDON_CONFIG_DIR` and `~/.config/andon` | `ANDON_CONFIG_DIR` |
| `ANDON_API_TOKEN` and the token saved with `andon api-token` | `ANDON_API_TOKEN` |
| `ANDON_CAPTURE_TOKEN` and the token saved with `andon capture-token` | `ANDON_CAPTURE_TOKEN` |
| `ANDON_CAPTURE_ENV` and `~/.config/andon/capture.env` (capture scripts) | `ANDON_CAPTURE_ENV` |
| `ANDON_UP_HOME` and your home folder | `$ANDON_UP_HOME/.andon` |
| `stateDir` in the config and `~/.local/state/andon` | `stateDir` (`andon up` sets it to `~/.andon/agent/state`) |
| `XDG_DATA_HOME` and `~/.local/share` | `XDG_DATA_HOME`, for the installer's files and the skill folder |
| The installer's and the app's launcher at `~/.local/bin/andon` | whichever is in the file; the app never replaces the installer's |
| Two `andon` commands on your `PATH` | the first one; `which -a andon` lists them in order |

In its own folders, Andon reads only the files on this page. A file another tool left in one of them, such as an `api.env` with an
`ANDON_API_TOKEN` line, is never read. The card commands (`andon show`, `edit`, `move`, `comment` and the rest) use
`ANDON_API_TOKEN` from the environment, or else the token saved in the config with `andon api-token`.

`ANDON_HOME` moves the agent's own paths that start in your home folder (its config, state, logs, `host-id`, service
file and skill folder), not the installer's files or `~/.andon`. Andon's tests and demo use it; you don't need it.

## `andon: not set up` while the agent is running

`andon status` says `andon: not set up; run: andon setup`, or `andon update` says
`andon: not set up; run the installer from your board`, yet the board shows the machine online and cards run. The
agent is fine: the `andon` in your terminal is reading a different config folder from the one the running agent uses.
The usual case is a computer with the desktop app, whose agent uses `~/.andon/agent`, and an `andon` in
`~/.local/bin` left by an earlier `install.sh`, which reads `~/.config/andon`.

1. Find the running agent and the file it runs:

   ```sh
   ps -axo pid,command | grep '\.mjs agent' | grep -v grep
   ```

   A path inside `Andon.app` (or `board/agent/andon-<version>.mjs`) is the app's agent. `~/.local/share/andon/andon.mjs`
   is the installer's.

2. See which config folder it was started with (use the pid from step 1):

   ```sh
   # macOS
   ps eww -o command= -p <pid> | tr ' ' '\n' | grep '^ANDON_CONFIG_DIR='
   # Linux
   tr '\0' '\n' < /proc/<pid>/environ | grep '^ANDON_CONFIG_DIR='
   ```

   No output means `~/.config/andon`.

3. See which `andon` your terminal runs and what it reads:

   ```sh
   which -a andon
   head -3 ~/.local/bin/andon
   andon doctor | head -1
   ```

   In the desktop app, **Preferences → The `andon` command** saying "Installed by the installer" means the same thing:
   your terminal runs the installer's `andon`, which reads `~/.config/andon`.

4. Fix it in one of these ways:

   - **The app's agent is the one you use:** move the installer's `~/.local/bin/andon` to the Trash, then install the
     app's in **Preferences → The `andon` command**. If `~/.local/share/andon/` and the old config in
     `~/.config/andon/config.json` belong to a machine the board no longer shows, clear them as
     [Remove a machine](https://andon-docs.pages.dev/machines/remove-a-machine.md) says, keeping `host-id`.
   - **For one shell only:** `export ANDON_CONFIG_DIR=~/.andon/agent`, then run `andon` as usual.
   - **The installer's agent is the one you use:** check that its service is running (`andon doctor`), and stop the
     app's local Andon if you don't need it.

After the fix, `andon doctor` shows `✓ config at` the folder from step 2, and `andon status` shows the machine the board
shows.
