Skip to content
AndonDocs
GitHub
Use the board / The board and doing work

Previews and annotations

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

A run can share the app it is building, running on its machine, as a preview link on its card. Open it to try the change before you merge it. Then Annotate a frame of it: drop pins and boxes where something should change, and send them to the agent as one reply.

Turn previews on for a machine

Previews, and the board’s direct terminal, need a tunnel on the machine: Tailscale or a Cloudflare quick tunnel. The machine’s setup asks once; the default is no tunnel.

Tailscale Cloudflare quick tunnel
Who can open a preview devices on your tailnet. A phone or iPad needs the Tailscale app anyone with the link. The link carries a token; without it the page refuses
Account a Tailscale account, with HTTPS certificates on none
Address https://<machine>.<tailnet>.ts.net:<port>, the same every time a new https://<words>.trycloudflare.com for each preview
Terminal the board on a tailnet device opens it directly; elsewhere it goes through the server the board opens it directly from anywhere

On the machine:

  1. Run andon tunnel tailscale or andon tunnel cloudflare.
    • Tailscale: install it and sign in first. Turn on MagicDNS and HTTPS certificates on the DNS page of the Tailscale admin console. On Linux, let your user configure serve once: sudo tailscale set --operator=$USER.
    • Cloudflare: the command installs cloudflared with Homebrew when it’s missing. Quick tunnels need no account, and Cloudflare gives them no uptime guarantee.
  2. Check it with andon tunnel status and andon doctor.

The board opens a terminal directly only on a machine whose agent is current; an older agent’s terminal goes through the server. Your sign-in never goes to the machine: the board asks the server for a one-time pass for each terminal it opens.

andon tunnel off turns previews off. --no-terminal keeps previews but leaves the terminal off the tunnel. See The andon command for every flag.

Open a preview

When a run starts its app, the link shows on the card as Preview · …. Click it to open the app in a new tab. The link closes when the run’s session ends.

A run shares only its own app: a port a process it started listens on, one working in the run’s workspace. The machine’s other servers, another run’s app and a port Docker forwards stay off the tunnel. The machine tells whose a port is with lsof, so a port preview needs a Mac or Linux machine.

The app is sent only the cookies it set itself. Your board sign-in, and other previews’ links, never reach it, even where the board and the machine share an address. A cookie the app’s page sets in script alone isn’t sent.

An app with no port to share, such as an iOS Simulator, an Android emulator or a macOS app window, shows as a picture of its screen instead: Preview · iOS Simulator, Preview · Android or Preview · window. It refreshes about twice a second while someone has it open. You can look, but not click. A window shows only an app the run built in its workspace or started itself, never another app on the machine.

Annotate a preview

Only the card’s owner annotates.

  1. Click Annotate on the preview link. Andon asks the run’s machine for a frame of the page, at the size of your window. New frame asks for another.
  2. Click to drop a numbered pin, or drag to draw a box. On a phone or iPad, tap for a pin, or press and hold, then drag, for a box.
  3. Type a note for each one. Paste an image into a note to add a reference picture.
  4. Click Request changes. The open annotations go to the run as one reply, with the marked frame. A run that has ended continues in its session.

The notes sit beside the frame, or below it on a narrow screen, with who wrote them and when. Each has Resolve, Reopen and delete, with Undo for 10 seconds.

When the agent has made its changes, take a New frame. Earlier pins show faded on it, marked drawn on an earlier frame, so you can check each one. A frame of another size lists them without placing them.

When the machine can’t take a frame

The dialog says why: no Chrome or Chromium on the machine, the preview closed with its session, the machine offline or its agent too old, or a machine someone else owns. Paste, drop or pick a screenshot instead and annotate that.

A web frame is the top of the page the link opens on. On a web preview, each pin also tells the agent which element it is on, unless the app forbids inline scripts or refuses to be framed.

Approve

Approve says the change looks right. It resolves the annotations that were sent. Ones you never sent stay as they are, unless you tick them to make a follow-up card of each.

Annotate a picture

An image the run made, or an image attached to the card, has Annotate in its lightbox too. It works the same way.

Reviews look at the picture too

A review round of a change you can see can start the app, capture it, and report what’s wrong on a frame. Its findings show as pins on that frame, signed Andon review · round 2, beside yours. A blocked one is answered on the board like any finding: Fix it, I handled it, Leave as is or Follow-up card. See Pull requests: review and merge.

The review’s browser only reads the preview: it doesn’t click, fill in forms, sign in or leave the preview’s own pages.