Skip to content
AndonDocs
GitHub
Run machines and deploy / Machines

Files on a machine

View as MarkdownThe same text, at this page's address plus .mdOpen in ClaudeAsk questions about this pageOpen in ChatGPTAsk questions about this page

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).

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) 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:

shell
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).

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 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) 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:

    shell
    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):

    shell
    # 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:

    shell
    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 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.