Skip to content
  1. Bridgey
  2. Help
  3. User guide

Bridgey user guide

Everything on one page: install, pairing, the clipboard and files, notifications, calls, codes, texts, connecting away from home and updates. Every release is a beta for now; there is no Stable release yet.

The same guide as in the Bridgey repository.

Bridgey by Round Robin connects an Android phone and a Mac over your own Wi-Fi, and away from home through Round Robin's connect service (on by default, see Connect away from home). It has no account. This guide covers the common tasks. For what has been tried on which devices, see compatibility.

Contents: install, pair, clipboard and files, notifications, calls, codes from messages, remote control, connect away from home, updates, permissions, reset, uninstall, troubleshooting.

Install

Both apps are on the releases page of round-robin-solutions/bridgey. Each release has an Android APK, a Mac DMG and ZIP, and a SHA256SUMS file.

Quick ways in: on a Mac, brew install --cask round-robin-solutions/tap/bridgey-rr; on Android, Obtainium keeps the app updated from the same releases. The steps below use the files directly.

Android

  1. On the phone, open the releases page and download the file ending in -Android.apk from the newest release without a "Pre-release" label.
  2. Open the file. Android asks you to allow installs from that app (your browser or Files). Allow it for this install.
  3. Open Bridgey RR (the launcher name) and follow the welcome screen.

To check the download, compare its SHA-256 with the line for that file in SHA256SUMS. Android requires every update to be signed with the same key as the installed app, so Bridgey only installs updates from its own releases.

Bridgey supports Android 8.0 and later.

Android with Obtainium

Obtainium installs and updates apps straight from GitHub releases. With it installed, open one of these links on the phone. It adds Bridgey with the right release filter for the channel, and Android still shows its own confirmation for every install. There is no Stable release yet, so use Beta for now.

Stable | Beta

Stable follows releases not marked "Pre-release". Beta follows Stable and Beta releases. Nightly follows every build.

Mac

With Homebrew:

brew install --cask round-robin-solutions/tap/bridgey-rr

The cask comes from round-robin-solutions/homebrew-tap. It installs the newest Stable release (until there is one, the newest Beta) and removes the download quarantine flag from the app, because the app is ad-hoc signed and not notarised yet. Homebrew 6 and later asks you to trust a third-party tap; naming the full cask as above trusts just that cask. The app updates itself afterwards, so brew upgrade leaves it alone; brew uninstall --cask --zap bridgey-rr removes the app and its data.

With the DMG:

  1. Download the file ending in -macOS.dmg and open it.
  2. Drag Bridgey by Round Robin to Applications.
  3. The first time, right-click the app and choose Open, or open System Settings > Privacy & Security and press Open Anyway. The app is not yet signed with an Apple Developer ID, so macOS asks once.
  4. Allow local network access when macOS asks. Bridgey needs it to find and reach your phone.

Bridgey needs macOS 13 or later.

The edition installs next to the original Bridgey. Both listen on the same port, so quit one before you run the other on a Mac.

Pair a phone and a Mac

Keep both on the same Wi-Fi. Open Bridgey on both.

  1. On the Mac, the menu-bar panel lists nearby phones. On the phone, open Settings > Devices and permissions > Pair a new device (or tap Add on the home screen).
  2. Choose the other device. Either side can start.
  3. Both screens show a six-digit code. Press Codes Match (Mac) and confirm on the phone only if the two codes are the same. If they differ, cancel: someone else may be on the network.

After this the devices reconnect on their own. To stop trusting a device, open it and choose Forget (it must be forgotten on both sides to be gone everywhere).

Send the clipboard and files

Clipboard

  • Mac to phone: copy on the Mac. With "Automatic clipboard" on (default), it reaches the phone without a tap. The Mac shortcut for "Send clipboard" is Control-Option-C (you can change it in Settings).
  • Phone to Mac: while Bridgey is open it is automatic. Otherwise tap Send copied item in the Bridgey notification, or add the Send copied item tile to Quick Settings. Android does not let an ordinary app read the clipboard in the background (Android 10 and later); see why.
  • Images and files: with Copy images and files on in Settings > Clipboard, copied images, videos and files move when you paste. This works between two Round Robin edition apps. With the original Bridgey only text up to 32 KiB moves.
  • Fresh screenshot: if you took a screenshot in the last minute, Send copied item sends it instead. This needs access to all photos.

Anything marked sensitive (for example by a password manager) is not sent.

Files

  • From the Mac: drop files on the panel, or use the send bar.
  • From the phone: tap the attach button in the send bar, or use Android's Share menu and choose Bridgey.
  • Several files go one after another in a queue. Each can be cancelled on its own. An interrupted send can be retried once the devices reconnect.
  • Where they land: Android saves to Download/Bridgey. The Mac saves to Downloads/Bridgey by default; change it in Settings > Files (Received files). A file never replaces an existing one.
  • Hidden files in folders: a folder skips hidden files (names that start with a dot, such as .gitignore) and system clutter (.DS_Store, ._ files, Thumbs.db). Two switches in Settings > Files on the phone and on the Mac, "Include hidden files when sending folders" and "Include system files when sending folders", turn each on; both are off by default. On the phone they also apply when a Mac downloads a folder from it.

Notifications

Phone notifications can appear on the Mac.

  1. On the phone, open Settings > Notifications and turn on Notification forwarding.
  2. Choose Notification forwarding and allow notification access for Bridgey in Android's own screen.
  3. On the Mac, allow notifications for Bridgey when asked.
  4. Under Notification apps, choose which apps may be shown on the Mac.

You can dismiss, act on or reply to a notification from the Mac when the phone app offers that. Dismissals sync both ways. A notification history on the Mac is off by default.

Calls

  • Call from the Mac: copy a phone number and press Call in Bridgey or Control-Option-P. In apps with macOS Services, select a number and choose Services > Call with Bridgey RR. By default the phone shows a notification; tap it to review the number in the dialer.
  • Call status and answer controls on the Mac: on the phone open Settings > Calls and turn on Call status and controls. Android asks for Phone permissions. After that the Mac shows incoming and active calls with Answer, Decline and Hang Up. Bridgey does not ask for contacts or call history and never dials emergency numbers itself.
  • Phone links: on the Mac, Settings > Calls > Phone links > Use Bridgey sends tel: links from your browser to Bridgey.

Codes from messages

When a text message has a one-time code, the Mac can show "Code 482913 from HDFC Bank" with Copy code. It is off by default.

  1. On the Mac: Settings > Notifications > Codes from messages > turn on Show codes from text messages. Choose Read codes: On this Mac (private) downloads a small model (253 MB, one time) and reads messages on the Mac. Cloud (Cloudflare) sends the message text to Round Robin's relay. See the edition notes for the details.
  2. On the phone (Android 15 and later): Android hides code text from apps it does not trust. Open Settings > Notifications > Codes from messages and tap Link this phone to the Mac. The Mac advertises over Bluetooth for a minute, Android's own dialog finds it, and you tap Allow once. Turn on Bluetooth (and, if Android finds no Mac, Location) on the phone. The Mac asks for Bluetooth permission the first time.
  3. With more than one Mac: the phone shows which Mac it is linked to and lets you pick which Mac to link.
  4. The phone shows Code access: allowed, hidden by Android or not linked.

If linking does not work, the phone shows a one-time ADB command to run from a computer, with a Copy button. Removing the link in Android settings may also turn off Bridgey's notification access.

Copied codes stay on the Mac, are marked so clipboard managers skip them, and are cleared after 60 seconds. Codes and message text are never written to logs or diagnostics.

Text messages

Read and answer your phone's text messages on the Mac. It is off until you turn it on.

  1. On the phone, open Settings > Text messages and turn it on for your Mac. Allow SMS access when asked; contacts access is optional (without it you see numbers instead of names).
  2. On the Mac, open Settings > Text messages and turn it on.

Then:

  • A text message notification on the Mac has a Reply field. Your reply goes through your messaging app when it can, or as an SMS. If replies from your messaging app do not arrive, turn on Send replies as SMS on the phone.
  • Messages (from the menu bar panel, or by clicking a text notification) shows your conversations. Pick a conversation to read it and reply; use New message to write to a contact or a number. On a phone with two SIMs, choose the SIM next to the send button.
  • Unread conversations come first, newest first, then the rest. Unread shows only those; opening a conversation takes you to the first unread message.
  • Right-click a conversation, swipe it, or use the buttons above it to mark it read or unread, pin, mute (no banners on the Mac), archive or delete it. Click Select (or Command-click) to act on several at once. Command-F searches every message kept on the Mac, Shift-Command-U marks read or unread, Command-Delete deletes.
  • Right-click a message to copy its text or code, forward it, see its details, or delete it.
  • These choices stay on the Mac; your phone's messaging app is not changed. Two things reach the phone: marking a conversation read also uses your messaging app's own Mark as read while its notification is still showing (the window says when it did), and Block on phone… opens Android's Blocked numbers screen, where you add the number yourself.
  • Deleting removes a conversation or message from this Mac only; it stays on your phone. A deleted conversation comes back when a new message arrives in it, and so does an archived one unless it is muted.
  • Group conversations can be read on the Mac; answer them on the phone.
  • Your messages go only to your own paired Macs, encrypted. Bridgey never becomes your default SMS app. Turning Text messages off, or forgetting the phone, deletes the copy on the Mac.

Remote control

The phone can act as a touchpad, keyboard and slides remote for a Mac. It is off on both sides until you turn it on, and only works between two Round Robin edition apps.

  1. Mac: Settings > Remote control: turn it on, and allow the phone. macOS asks for Accessibility access when it first becomes usable.
  2. Phone: Settings > Remote control: turn it on. The Mac's device page then shows a Remote control entry.
  3. Start a session. While it runs, the Mac shows a pill at the top of the screen with Stop, and the menu-bar icon changes. Control-Option-Escape on the Mac also stops it.

The Mac keeps a 30-day session record (device, times and counts, never what you typed) that you can clear in the same pane.

Connect away from home

Your paired devices stay connected when they are not on the same Wi-Fi, with no VPN on the phone. It is on by default.

  • What it contacts. While it is on, Bridgey keeps a connection to connect.roundrobin.in, which helps your devices find each other. When they cannot reach each other on the same Wi-Fi (or a private network such as Tailscale, or directly over the internet), the traffic goes through a Round Robin relay.
  • What the relay sees. Only encrypted data: your devices' public addresses, and the timing and size of the traffic. Never device names, content or file names.
  • Turn it off. Settings > Devices > Connect away from home, on the phone or the Mac. With settings sync on, your other devices turn it off too. Once you turn it off it stays off, including after updates. Same Wi-Fi keeps working either way.

Update channels and updates

Bridgey updates itself. Open Settings > Updates on either device.

ChannelFor
Stable (default)Tested releases. Best for most people.
BetaNew features before they reach Stable.
NightlyBuilt from every change. Expect rough edges.

Switching to a steadier channel never downgrades; it waits for that channel's next newer build. The apps check daily, and Check now checks at once. An update installs when you tap Install (the Mac shows each step with Install, Later and Skip), when you use Update all on a paired device, or by itself with Update all devices automatically (below). On Android 12 and later an update you started usually finishes without a second tap; when Android still wants one, Bridgey shows "Tap to finish updating Bridgey". On Android the download must match its published checksum and be signed with the same certificate as the installed app. On the Mac the update must carry a valid EdDSA signature. Details are in the edition notes.

Update all

When one of your devices has an update, Update all appears on the phone's home screen and in the Mac's menu-bar panel, and in Settings > Updates on both. It updates every device connected to the one you are using: on the phone, all connected Macs and the phone; on a Mac, its connected phones and that Mac. Macs are not paired to each other, so to update two Macs at once, start it from the phone.

  1. Tap Update all. The preview lists each device with its version now and after, and its channel. Devices it skips are listed with the reason, for example not connected, or "Update this one by hand" for a device without this feature.
  2. Confirm. The other devices update and restart on their own. The device you are using goes last, after a 10-second countdown; choose Later to restart it when you are ready.
  3. Watch each device's progress. A device that fails shows Retry. "Waiting for you on OnePlus 11" means the phone wants a tap: open the notification on the phone.

Each device stays on its own channel and only installs its own signed update. If a device starts again on its old version, Bridgey says "Update didn't apply" and does not try that version again by itself. To stop other devices from starting updates on one device, turn off Let paired devices start updates on this device in its Settings > Updates.

Update all devices automatically

With Update all devices automatically on (Settings > Updates; on by default for Beta and Nightly, off for Stable), a new version reaches every connected device without a tap. Your devices check every 30 minutes on Beta and Nightly (every 6 hours on Stable) and when they wake up. When one finds a new version, the other connected devices update first and it restarts last.

  • It waits while you are on a call, sharing your screen, using remote control, sending or receiving files, downloading from Phone files, or in setup or pairing, on any of your connected devices, and looks again every few minutes.
  • A short notice says what is updating. Bridgey restarts after 60 seconds; choose Later to put it off for an hour. After three Laters it waits until you step away (the Mac idle or locked, or the phone's screen off while it charges).
  • A device updated this way says "Started automatically by" the device that started it, and the activity stream lists what happened, for example "Updated automatically to 0.10.0-rr.1-beta.11" or "Waiting: call in progress".
  • Settings > Updates shows what it is doing now and how the last automatic update went.
  • With settings sync on, turning it on or off on one device does the same on your other devices.

On a Mac you can also start it from Terminal: "/Applications/Bridgey by Round Robin.app/Contents/MacOS/BridgeyMac" --update-all checks now, updates the connected phones and then the Mac, and prints what it did.

Permissions

Bridgey asks for each optional permission only when a feature needs it.

On the phone, Settings > Privacy > Permissions lists every optional permission with its state (allowed or not) and a Manage button that opens the right Android screen. The first time a feature needs a permission, Bridgey explains why and what stops working without it. If you decline, only that feature stays off.

If you do not see this screen, you are running a build from before it was added; update first.

What the optional permissions are for:

PermissionUsed for
Notifications (Android 13+)The connection notification, transfer progress and Send copied item
Notification accessForwarding phone notifications; reading code messages
SMSText messages: your conversations on the Mac and sending replies (only if you turn it on)
ContactsText messages: names instead of numbers, and finding a contact for a new message
PhoneCall status and Answer, Decline, Hang Up (only if you turn on Call status and controls); choosing the SIM for Text messages on a dual-SIM phone
PhotosSending a fresh screenshot (needs all photos)
Battery optimisationStaying connected while the phone sleeps
Install unknown appsInstalling Bridgey's own updates
Companion link (Bluetooth dialog)Android 15+ code access
Logs (ADB only)The optional "Background clipboard (advanced)"

On the Mac: Local network (always), Notifications (for phone alerts), Bluetooth (linking for codes), Accessibility (remote control) and Automation (Music or Spotify control). Bridgey does not ask for location, contacts, SMS, call history, camera, microphone or screen recording in the normal build.

Reset local data

On the phone, open Settings > Privacy > Reset Bridgey on this device. There are four choices. Each asks you to confirm and lists what it will delete. In short:

  • Activity and logs: the activity stream and the diagnostics log.
  • Downloaded models and caches: downloaded files and cached items that Bridgey can fetch again.
  • Settings: your preferences, back to defaults.
  • Everything, including pairings: all of the above, and the trust records. You must pair again.

Each choice's confirmation screen is the source of truth for what it deletes. If you do not see this screen, you are running a build from before it was added. The Mac has its own Clear buttons in Settings > Privacy (Activity, Logging). Resetting one device does not change the other.

Uninstall

  1. On each device, Forget the other, so no stale trust record is left.
  2. Android: uninstall Bridgey RR from Android's app settings. If you linked the phone for codes, also remove the link in Android's companion-device settings.
  3. Mac: quit Bridgey, move Bridgey by Round Robin from Applications to the Bin. Then, if you want the data gone, delete ~/Library/Application Support/in.roundrobin.bridgey (pairing keys, activity, diagnostics, models) and ~/Library/Caches/in.roundrobin.bridgey.

Files you received stay in Download/Bridgey and Downloads/Bridgey.

Troubleshooting

The devices do not find each other. Check both are on the same Wi-Fi. Some guest or office networks block devices from seeing each other. On the Mac, check System Settings > Privacy & Security > Local Network allows Bridgey. Press Look for devices again (the refresh button on the phone's home screen, or in the Mac panel), or Retry now on a paired device. Check the original Bridgey is not running on the Mac.

It disconnects overnight or when the phone sleeps. Allow Bridgey to stay connected: Settings > General > "Stay connected while the phone sleeps". Many phones add their own limit; see compatibility. On OnePlus, open App info > Battery usage and allow background activity.

Notification access will not turn on (Android 13 and later). An app installed from a file or a browser is blocked from this switch until you allow restricted settings. Setup shows the steps when it sees this; you can also do them yourself: Settings > Apps > Bridgey, tap the three dots at the top right, tap Allow restricted settings, then turn on notification access again. On some phones the three dots appear only after Android has blocked the switch once, so tap Allow in Bridgey first.

Phone notifications do not appear on the Mac. Check Notification forwarding is on, Bridgey has notification access on the phone ("Needs notification access" means it does not), the app is chosen under Notification apps, and the Mac allows Bridgey notifications.

Copying on the phone does not reach the Mac. This is Android's limit. Open Bridgey, or tap Send copied item.

No code appears for a text message. Check Codes from messages is on at the Mac, the code model is downloaded (or Cloud chosen), and on Android 15 and later that the phone shows Code access: allowed. If it says hidden by Android or not linked, link the phone.

Remote control says Accessibility is needed. Allow Bridgey in System Settings > Privacy & Security > Accessibility. After an update you may need to switch it off and on again in that list.

Something else is wrong. Export diagnostics from both devices, then open an issue at github.com/round-robin-solutions/bridgey/issues. Do not paste private content into the issue.

More help