Previews and annotations
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:
- Run
andon tunnel tailscaleorandon 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
cloudflaredwith Homebrew when it’s missing. Quick tunnels need no account, and Cloudflare gives them no uptime guarantee.
- 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:
- Check it with
andon tunnel statusandandon 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 ·
Annotate a preview
Only the card’s owner annotates.
- 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.
- 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.
- Type a note for each one. Paste an image into a note to add a reference picture.
- 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.
