Devices

Bogen on two of your machines, say a desktop and a laptop, can hold the same files and merge what you change on either, also while one of them is asleep or offline. They talk over Tailscale only. There is no Bogen cloud in between.

What syncs

• Files: new ones, renames and deletes. A delete that meets an edit made on the other side at the same time keeps the edit and brings the file back.
• Every edit, merged per value; text merges per character.
• Assets, checked by hash and size.
• Brands, libraries, change logs and named commits. Automatic commits stay on the device that made them.
• Who has a file open on the other device and what they select. Cursors only when you turn that on in the Agents tab.

Agents and their runs stay on the device where they run. Home screen folders, branch lists and code project links are per device too.

When both sides changed the same value while apart, Bogen keeps one and writes a conflict note. The Sync section of the Agents tab shows both values, with Use the other and Dismiss. When a file changed while nobody had it open, a banner says once what changed.

What you need

• Tailscale, signed in on both machines.
• Bogen on both, ideally the same build. Each tells the other its version, and bogen status, bogen peer status, bogen doctor and the sync indicator in the editor's top bar say when they differ.
• TCP port 29990 open between the two over Tailscale. See Firewall and tailnet policy.

Pair two devices

On the first device:

bogen peer pair --name Desktop

This turns on the Tailscale listener, saves that, and prints a command:

On the other device, run:
  bogen peer add http://100.x.y.z:29990 --token <token> --name 'Desktop'

Run that line on the second device. One command pairs both ways. To keep the token off the command line, put it in BOGEN_PEER_TOKEN and leave out --token.

The listener binds only to the address from tailscale ip -4, and everything on it needs the device's token. If Tailscale comes up after Bogen, the listener follows. Files sync through their own link there; the HTTP routes that start agent runs or post comments, and those for brands, libraries, live site mode and code projects, are closed on it.

Manage paired devices

--json gives the output of list, status and pair as JSON.

bogen serve --tailnet also listens on the Tailscale address, for that run. On Omarchy, integrations/omarchy/install.sh --tailnet (or bogen omarchy install --tailnet) makes the user service do so.

Firewall and tailnet policy

Two things can stand between your devices, and both need the owner of the machine or the tailnet:

1. The firewall. Omarchy's ufw refuses everything incoming. On each device:

``sh sudo ufw allow in on tailscale0 to any port 29990 proto tcp comment bogen-sync ``

The Omarchy installer with --tailnet offers to do this.

1. Your Tailscale policy. A tailnet with its own access rules has to allow TCP port 29990 between the devices, in the access controls of the Tailscale admin console.

bogen doctor tells these apart where it can: a device that answers Tailscale ping but not TCP on 29990 has a firewall or a policy in the way; one that refuses the connection has nothing listening. ufw's rules can only be read as root, so without passwordless sudo it prints the rule instead.

Update another device

From a checkout on one Omarchy machine:

bogen peer deploy my-laptop --dry-run   # says what it would do, changes nothing
bogen peer deploy my-laptop

Over ssh, this copies the current build and the Omarchy integration to ~/.local/share/bogen-app there, finds Node (through mise, and installs it with mise only if there is none), runs the installer with --tailnet, restarts the service, and reports the version that answers. It is safe to run again, and it does not touch your designs. integrations/omarchy/deploy.sh is the same script.

It has updated a real second device, the MacBook Air described under Limits. The tests run it against stand-ins for ssh and systemd.

A Mac

integrations/macos has an installer, an uninstaller and a deploy script for a Mac: a LaunchAgent that runs bogen serve --tailnet, a Bogen.app that opens the window and .bogen files, and a bogen wrapper. From a Linux checkout, integrations/macos/deploy.sh <ssh-host> --name MacBook builds, copies, installs and pairs in one go. See integrations/macos/README.md.

None of it has run on a real Mac yet. The scripts pass their checks on Linux against stand-ins for the macOS commands; expect to fix something small the first time.

iPhone and iPad

Your phone does not run Bogen. It opens the Bogen on your computer, through Tailscale, as an app on its Home Screen. Files you open there are also stored on the phone, so you can look at them and edit them without the computer. The edits merge when it is back.

What you need

• Tailscale on the phone, signed in with the same login as the computer.
• Bogen running on the computer, as the user service or with bogen start.

Set it up

1. On the computer:

``sh bogen phone on ``

This starts a listener on 127.0.0.1:29991, saves that so it comes back after a restart, and runs tailscale serve --bg --https=29443 http://127.0.0.1:29991. It touches no other port of tailscale serve. It prints the address, such as https://omarchy.tail1234.ts.net:29443/, with a QR code.

1. Let the phone through your tailnet policy. A tailnet with its own access rules has to allow TCP port 29443 from your phone to the computer. Only you can change that, in the access controls of the Tailscale admin console. bogen phone on prints a rule to add, for example:

``json {"src": ["[email protected]"], "dst": ["100.x.y.z"], "ip": ["tcp:29443"]} ``

If a rule already lets your phone reach the computer on other ports, add tcp:29443 to it. bogen doctor reads the rules Tailscale gives the computer and says, per phone, whether it gets in.

1. Pair the phone:

``sh bogen phone pair ``

or, in the editor on the computer, open the Agents tab and choose Pair a phone under Phone. You get a code like K7QM-3XTP and a QR code.

1. On the phone, scan the QR code with the camera and open the link in Safari. Tap Share, then Add to Home Screen, then Add.

1. Open Bogen from the Home Screen and type the code. The code works once, for ten minutes.

The app on the Home Screen keeps its own storage, apart from Safari, which is why the code is typed there and not in Safari. To use Bogen in Safari instead, choose Use Bogen in Safari instead on the page the QR code opens.

Who gets in

Three things have to hold for every request:

• It comes through tailscale serve, from a Tailscale login on the allow list. By default that is only the login that owns the computer. A device shared into your tailnet from another login does not get in. bogen phone on --login [email protected],[email protected] sets the list.
• It is for the computer's own ts.net name on the HTTPS port, and a page's Origin is that same address. That keeps other sites, and other apps behind tailscale serve on the same name, out.
• It carries the token of a paired phone. Each phone has its own, kept in a cookie that pages cannot read. bogen phone remove <id>, or Remove in the Agents tab, ends it at once.

A paired phone counts as you in person: it can start agents, comment for them, and accept or discard their proposals. It cannot reach the computer itself: no files on its disk, no linking of code projects, no live site mode, no captures of addresses on its local network, no MCP, and no settings of devices or phones.

On the phone

On a phone, Bogen has three tabs:

• Inbox: what waits for you. Proposals your agents made, comment threads that are still open, and agent runs that finished. Tap a proposal to compare before and after with a slider, then accept or discard it, or ask for changes.
• Files: your files. Keep stores a file and its images on the phone.
• Ask: ask Claude or Codex on the computer for a change to a file. While it works you watch the canvas and its steps, and can stop it. What it makes comes back as a proposal you can accept or discard right in the thread.

Tapping a file opens it in a screen made for touch:

• The top bar: ‹ Files goes back, the file's name is in the middle, and the current page is on the right. Tap the page to see every page with how many boards it has, and the boards of the current page as small pictures with their widths. Tap a page to switch to it, and a board to put it on the screen.
• The canvas: pinch to zoom, drag to look around. Under it, where you are (page, board, zoom), ‹ and › to step to the board before or after, and − and + to zoom. A quick sideways flick with one finger also steps between boards, while the board fits across the screen; zoomed in, a sideways drag only pans. Undo and redo appear in the corner once you have changed something, and take back only your own changes.
• The tools at the bottom, each a sheet over the canvas, which stays in view above it. Drag a sheet down by its handle to close it, or tap its tool again.
  • Layers: the layers of the board, 44 px rows. Tap one to select it and bring it into view, then Edit ›.
  • Edit: Text to change a layer's words in a plain field; Fill for colours from the file's tokens and the brand's palette; Layout for width, height, padding and gap, stepped along the spacing tokens; Type for the file's text styles and the brand's type scale. Every change is one step of undo. Done closes it.
  • Comment: tap a pin to read its thread and reply, or Resolve it. With the sheet open, tap a spot or a layer to place a new comment. Mentioning @claude or @codex starts that agent on the computer, as on the desktop.
  • Ask: ask Claude or Codex about the selection, or the board in view, with quick suggestions. The answer comes back in the sheet as a proposal to accept or discard.

An iPad, or any touch screen that comes through the phone listener, gets the same screen, with the sheets as a panel at the side. The desktop editor, made for a mouse and a large screen, is still there under The desktop editor at the bottom of the page list, behind a warning.

Fields are 16 px or more, so iOS does not zoom into them, and the page itself can still be zoomed. While the keyboard is up, the field of a sheet stays right above it.

What works offline

• The app itself, once it has been opened online.
• Every file you opened on the phone, as it was when you last had it open. You can view and edit it; a banner says that you are offline and that your edits are saved on the phone. When the computer can be reached again, the edits merge with what changed there in the meantime.
• The list of files on the home screen, as it was when you last saw it. Files that are not on the phone are dimmed.
• Files you keep, with their images and fonts, also when you never opened them on the phone. Choose Keep in Files (or Keep on this phone in a file's menu in the full editor's home screen). A kept file stays; the twelve most recently opened other files stay too, and older ones make room.
• The inbox as it was when you last saw it.

Nothing that needs the computer works offline: agents, comments to agents, exports, captures, history and thumbnails.

Turn it off

bogen phone off

This stops the listener and takes port 29443 out of tailscale serve. Paired phones keep their pairing for when you turn it on again; remove them with bogen phone remove <id>.

Limits

• The phone has been tried in Chromium with a phone's and an iPad's screen size and touch, through a stand-in for tailscale serve, not yet on a real iPhone or iPad. How the keyboard and the sheets behave in iOS in particular has not been tried there.
• A removed phone keeps the files it stored until the app is deleted from it.
• Sync has run between two real machines over Tailscale: an x86_64 PC and an M1 MacBook Air, both on Omarchy (the MacBook on Arch Linux ARM). An edit arrived in under about 0.1 s each way, a restarted service caught up in under a second, and the same file rendered the same on both. Both sides editing while apart was tested on one machine only, and a laptop going to sleep has been simulated, not tried.
• An open editor counts as someone being there, so the "while nobody had it open" banner does not show for files that stayed open.
• A paired device on an older build does not get presence (who has a file open), since it would drop the connection over a message it does not know.