The desktop app
The desktop app is Andon in a window of its own on macOS, Windows or Linux. Use it to run Andon on your own computer with nothing to deploy, or to keep several Andon instances one keystroke apart. It loads each instance’s own board, so what you see is what a browser shows, plus what a browser tab can’t do:
- a tray icon with the “needs you” count, and the Dock badge on macOS
- native notifications that open their card when you click them
- quick capture from anywhere: ⌃⌥⌘Space on a Mac, Ctrl+Alt+Space on Windows and Linux. Change it under Preferences → Quick capture. An install that still used ⌥⌘Space, which macOS keeps for Finder search, moves to ⌃⌥⌘Space
andon://links, and a native right-click menu on cards- instant switching between instances: ⌘1…⌘9 on a Mac, Ctrl+1…Ctrl+9 on Windows and Linux
On Windows the window has no title bar or menu strip, as on a Mac: the bar with the search box is the caption (drag it to move the window, double-click it to maximize) and holds minimize, maximize and close. The menu button at its left opens the app’s menus, so Andon → … in this guide is that button’s Andon submenu.
Where the app comes from
Releases are built for macOS on Apple silicon (signed and notarised by Apple), Windows x64 and Linux x64 and arm64. The Windows and Linux builds aren’t signed. A release updates itself (see Updates).
This repository doesn’t link a download. If you weren’t given an installer, build the app from a clone. You need
Node 22, pnpm 10 and a Rust toolchain (rustup; on macOS the Xcode command line tools, on Linux the
webkit2gtk packages Tauri lists).
git clone https://github.com/psci-labs/andon && cd andonpnpm installpnpm --filter @andon/desktop build:app:local # the app, with the local server insideThe bundle is in apps/desktop/src-tauri/target/release/bundle/. On macOS, copy macos/Andon.app to Applications.
A build you make yourself isn’t signed and has no updater.
Opening a build that isn’t signed
A build made on the same Mac opens as it is. macOS quarantines a copy someone sent you: right-click the app → Open and confirm, or clear the flag:
xattr -dr com.apple.quarantine /Applications/Andon.appOn Windows, SmartScreen asks once: More info → Run anyway. On Linux, an AppImage needs chmod +x first.
Run Andon on this computer
The app can run a whole Andon on your computer: the server, its Postgres and the board, on http://localhost:8787,
with the data in ~/.andon. It suits trying Andon or working alone.
-
Open the app. A fresh install starts with a short welcome. Finish or skip it.
-
There’s nothing to choose: the app sets Andon up on this computer by itself (Setting up Andon on this Mac, a minute the first time) and installs the
andoncommand, forandon status,andon doctorand the rest in a terminal. If it doesn’t start, the page says why and Try again runs it again. Ifandon upalready runs here, the app adds it instead. -
The app opens the new instance, called Local, on
/setup. Create the owner (you) and the instance’s org. Andon then connects this machine’s agent to it. The agent may work in~/Projects,~/orca,~/Andonand whichever of~/Developer,~/code,~/src,~/dev,~/Sites,~/GitHub,~/reposand~/workexist, and finds repositories in those that exist. For a repository anywhere else, runandon repos add <path>. -
Follow
/welcome, three steps:- Connect a machine: check this machine is there. If its agent is behind the board, run the update command shown.
- Add a team: pick a repository your machines can see, or a folder on one of them, and a preset.
- Turn on Autopilot for that team, or Leave it off.
The last step also offers Add a first card, Use it from your phone and a two-minute tour: a practice board where one pretend card goes from idea to merged PR. Each is optional.
Take the tour in the account menu walks you round the board itself, whenever you want it.
The local instance is ordinary processes, not a system service. While the app is closed nothing restarts it after a
crash or a reboot: open the app again. On a Mac, Start it when you log in starts it at each login, but doesn’t
restart it after a crash (Keep it running).
It sends no email: invites and sign-in codes go to
~/.andon/mail.log. Its agent gets the Open preset, which runs any recipe from your org without approving it here
(presets).
On Windows the app runs the server, Postgres and the board, but no agent, because the agent needs tmux. Cards then run on a Mac or Linux machine, or in WSL2 on the same PC (Windows machines).
Fix this machine’s policy in the app
The machine’s local policy can hold work back: a recipe that isn’t approved on it, auto merge off, an agent it doesn’t run. On the Local instance, Settings → Machines puts a button beside each fix on the card for this computer:
- Approve beside a recipe that needs approval, or approval again after an edit, on this machine.
- Allow, Allow all or Run any recipe on a Local policy row that blocks or limits something.
The button runs that row’s andon policy … command on this computer, and the row updates within a few seconds. A
permission mode, a tools list and signed commands have no button: run their command in a terminal. The buttons show
only in the app, on its Local instance, for the machine its own agent enrolled. Any other machine’s policy is
changed on that machine.
Keep it running
Andon keeps running when you quit the app. If Andon isn’t answering when the app opens, the app starts it. If Andon stops later, the app restarts it. Preferences has the controls:
- Start it when the app opens: on by default.
- Start it when you log in (macOS): off by default. It starts Andon at login without opening the app.
- Restart and Stop. A stop stays stopped until you start it again.
Reach it from your phone and other computers
Other devices reach Andon on your computer over Tailscale, and only while the computer is awake and Andon runs.
- Put this computer and the other device on the same tailnet.
- On the board, open Settings → Machines. Reach this Andon from other devices shows its Tailscale addresses.
If it has no HTTPS address yet, press Share over HTTPS. Andon restarts on that address, which takes a few
seconds. Passkeys and notifications need the HTTPS address. A passkey is tied to the address it was made on: one
made on the HTTPS address doesn’t work on
localhost, and one made onlocalhostdoesn’t work on the HTTPS address. - On the other device, open that address. Connect another device, in the account menu and as the QR button beside the org’s name, shows it as a QR code for a phone’s camera.
Settings → Machines checks that the HTTPS address loads each time it opens. When it doesn’t, it says why, and Restart sharing turns sharing off and on again.
To run cards on another computer, add it as a machine: Settings → Machines → Add machine shows the install.sh
line with the address that computer can reach.
Connect to an existing Andon
The app is also a window onto any other Andon: your team’s, a self-hosted one, or the hosted service.
- Press + on the rail (on a fresh install, Connect to an existing Andon instead under the setup) and type its address. On a fresh install the setup carries on meanwhile: when it’s ready, the app adds Andon on this computer to the rail as Local, and you stay on the address you’re typing. A build without the local server goes straight to the address.
- Sign in to its board.
Each instance keeps its own sign-in, so sessions never mix. Switch between them with ⌘1…⌘9 (Ctrl on Windows and Linux) or from the rail. The search box above the board (⌘K) searches only the instance you’re looking at, so what you type never reaches another instance. To search another one, switch to it first.
Signing in inside the app
Email and password, emailed codes and an authenticator app work in the app’s window. Some sign-ins open your browser instead, and the app picks the session up when you finish:
- Google and GitHub don’t allow sign-in inside an app’s window.
- Use a passkey in your browser: passkeys work only in the browser.
- Sign in with your browser: for a password manager, which can’t fill the app’s window.
Once you’re signed in there, the browser asks Sign in to the desktop app?, naming the instance and your account. Choose Sign in to the app only if you just started this from the app on this computer; Don’t sign in sends nothing.
Instances your home instance is connected to
When an instance in the app is your home instance, the app offers the instances it is connected to, one at a time: Add name too? (for example Add Work too?), with its address, name and colour. Add to the rail adds it, and you sign in to it there. Not now leaves it out. Either way the app doesn’t ask about that instance again; add it later with Connect to an existing Andon.
Updates
A release checks for a new version at launch and every six hours, and downloads it in the background. A notification and Andon → Restart to Update to … then offer it. Nothing installs until you choose that. Andon → Check for Updates… checks at once.
The app stops Andon on this computer before the new version goes in, and the new version starts it again. On Linux only
the AppImage updates itself. Update a .deb or .rpm install by installing the new package.
The board inside an instance updates whenever its server does. When a new version of the board is out, the board asks whether to reload.
The keychain prompt on macOS
The first time a board opens, macOS may ask for your login keychain password for “Andon WebCrypto Master Key”. The board keeps a signing key for this device in protected browser storage, and macOS guards it with a key in the keychain. Always Allow is the right answer. A build that isn’t signed looks like a new app after every rebuild, so the prompt comes back until you use a signed build.
The andon command
The andon command the app installs is ~/.local/bin/andon. It runs the agent inside the app against Andon on this
computer, so a terminal has andon status, andon doctor and the rest without running install.sh. Preferences →
The andon command has Install and Remove. andon update from it tells you to update the app instead. The app never overwrites an
andon that install.sh put there, and it doesn’t offer the command on Windows or in an AppImage.
When install.sh’s andon is there, the card asks it its version. If that isn’t the version of the agent inside the
app, the card’s dot turns amber and it names both: this computer runs two agents of different versions. The
installer’s updates from its board, so run andon update in a terminal to bring it up to date, or update the app.
The app’s andon reads the agent config in ~/.andon/agent; the installer’s reads ~/.config/andon. If a terminal
says andon: not set up while the app’s Andon runs, it is running the installer’s: see
Files on a machine.
