# 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](#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](https://tauri.app/start/prerequisites/)).

```sh
git clone https://github.com/psci-labs/andon && cd andon
pnpm install
pnpm --filter @andon/desktop build:app:local   # the app, with the local server inside
```

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

```sh
xattr -dr com.apple.quarantine /Applications/Andon.app
```

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

1. Open the app. A fresh install starts with a short welcome. Finish or skip it.
2. 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 `andon` command, for `andon status`, `andon doctor` and the rest in a
   terminal. If it doesn't start, the page says why and **Try again** runs it again. If `andon up` already runs here,
   the app adds it instead.
3. 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`, `~/Andon` and whichever
   of `~/Developer`, `~/code`, `~/src`, `~/dev`, `~/Sites`, `~/GitHub`, `~/repos` and `~/work` exist, and finds
   repositories in those that exist. For a repository anywhere else, run `andon repos add <path>`.
4. Follow `/welcome`, three steps:
   1. **Connect a machine**: check this machine is there. If its agent is behind the board, run the update
      command shown.
   2. **Add a team**: pick a repository your machines can see, or a folder on one of them, and a preset.
   3. **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](#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](https://andon-docs.pages.dev/machines/orca-or-direct.md#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](https://andon-docs.pages.dev/machines/windows.md)).

### 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](https://tailscale.com), and only while the computer is
awake and Andon runs.

1. Put this computer and the other device on the same tailnet.
2. 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 on `localhost` doesn't work on the HTTPS address.
3. 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.

1. 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.
2. 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](https://andon-docs.pages.dev/guide/needs-you.md#needs-you-everywhere), 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](https://andon-docs.pages.dev/machines/files-on-a-machine.md#andon-not-set-up-while-the-agent-is-running).
