# Annex

> Annex is a free, open-source app (MIT licence) that turns another computer into a second monitor for yours, or shows its screen on yours. It works between Mac, Windows and Linux in any combination, over your local network, a cable, direct Wi-Fi or the internet, and is encrypted end to end. No account, no tracking.

Website: https://getannex.dev · Docs: https://getannex.dev/docs · Source: https://github.com/NRanjan-17/Annex

## At a glance

- Modes: Extend (the other computer becomes a second display), Mirror (see and use its screen), Control (one mouse and keyboard for both, with a shared clipboard).
- Platforms: macOS 14 or later (Apple silicon and Intel); Windows 10 (2004) or 11 (x64 and ARM); Linux (Ubuntu, Debian, Fedora, openSUSE, Raspberry Pi OS; x86_64 and arm64).
- Any pairing works in either direction: Mac to Windows, Windows to Linux, Mac to Mac, and so on.
- Delay: about 8 ms on a direct link, with hardware video encoding. Extend matches the other screen's refresh rate, up to 240 Hz. Mirror goes up to 2560×1600 at 60 fps. HEVC when both computers support it, otherwise H.264.
- Links: local network, Ethernet, Thunderbolt or USB4 cable (Mac to Mac), direct Wi-Fi (Windows hotspot), peer-to-peer Wi-Fi (Mac to Mac), or the internet with a 6-character code.
- Security: TLS 1.3 over QUIC; computers pair once with a 6-digit PIN (SPAKE2, the PIN is never sent) and remember each other's keys.
- Privacy: on a local network Annex never talks to a server. Over the internet, the code server only swaps the two computers' addresses; a relay is used only when a network blocks a direct link, and it stays encrypted.
- Also: sound both ways, copy and paste, drag-and-drop file transfer, headless sharing (Raspberry Pi, Mac mini over SSH), automatic signed updates.
- Price: free. No paid version, no sign-up.

## Get started

Install Annex on both computers, then pair once.

### macOS

1. [Download the .dmg](https://github.com/NRanjan-17/Annex/releases/latest/download/Annex-macos-universal.dmg) and drag Annex to Applications.
2. Allow `Local Network` when asked.
3. To share: allow `Screen Recording` once.

### Windows

1. Download [x64](https://github.com/NRanjan-17/Annex/releases/latest/download/Annex-Setup-x64.exe) or [ARM](https://github.com/NRanjan-17/Annex/releases/latest/download/Annex-Setup-arm64.exe) and run it. Or in PowerShell: `irm https://raw.githubusercontent.com/NRanjan-17/Annex/main/scripts/install.ps1 | iex`
2. If SmartScreen appears: `More info` → `Run anyway`.
3. Allow Annex on `private networks`.

### Linux

1. Run `curl -fsSL https://raw.githubusercontent.com/NRanjan-17/Annex/main/scripts/install.sh | sh`
2. Or install the `.deb` or `.rpm` from the [latest release](https://github.com/NRanjan-17/Annex/releases/latest).
3. Open Annex from the app menu.

### Pair

1. Open Annex on both. Each shows the other under `Nearby` within a few seconds.
2. Connect from one; the other shows a 6-digit PIN. Type it. After that, they connect without a PIN.

## Features

### Extend

The other computer becomes a second monitor. Drag windows onto it.

1. On the computer whose screen you'll use, turn on `Share this Mac` or `Share this PC`.
2. On the other, pick it under `Nearby`, then `Extend Display`.
3. Drag a window off the edge of your screen: it appears on the other computer.

Note: A Windows PC that shares needs the `Extend-mode display driver`, an option in its installer.

### Mirror

See and use another computer's screen in a window or full screen.

1. Turn on sharing on the other computer.
2. Pick it under `Nearby`, then `Show Its Screen`.
3. Press `Esc` to leave.

### Control

Use one mouse and keyboard for both. In Extend, the pointer crosses between screens.

1. On the sharing computer, open `Paired Devices` and turn on `Can use this Mac's mouse and keyboard` for your device.
2. On a Mac, allow `Accessibility` when asked.
3. On your computer, turn on `Control the other computer` in Settings, then connect.

Note: Leave with `⌃⌥⇧Q` on a Mac or `Ctrl+Alt+Shift+Q` on Windows.

### Over the internet

Connect two computers on different networks with a 6-character code.

1. On the sharing computer, open `This Mac` or `This PC`, find `Over the internet`, and click `Get a Code`.
2. On the other, choose `Connect by Code or Address…` and type the code. It works once, for 10 minutes.
3. The first time, type the PIN too.

Note: The relay is used only when a network blocks a direct link (some internet providers, college and office networks). It stays encrypted: nothing you share is stored or seen. Limit: 10 relayed sessions a day per sharing computer. Your own relay, under `Internet` in Settings, has none.

### Your own server and relay

Use your own code server or relay instead of Annex's.

1. Open `Internet` in Settings.
2. `Server`: your code server's address, like `wss://rendezvous.example.com`. Set the same on both computers.
3. `Your relay`: a TURN server, like `turn:relay.example.com:3478`, then its username and password. The sharing computer is the one that needs it.

Note: Leave both empty to use Annex's. The code server is a small Cloudflare Worker in the repository; any standard TURN server works as a relay. Step by step: the [guide](https://github.com/NRanjan-17/annex/blob/main/docs/GUIDE.md#your-own-code-server-and-relay).

### A sharper picture (HEVC)

When both computers support HEVC, the picture is sharper at the same speed. Otherwise it's H.264.

1. Nothing to do: it's on by default, in `Settings → HEVC`.
2. Windows: to receive HEVC, install the `HEVC Video Extensions` from the Microsoft Store if your PC doesn't have them.
3. Linux: install `gstreamer1.0-libav` to receive it. Sending needs an HEVC encoder on the graphics chip.

Note: When several computers watch one screen, it's HEVC only while all of them support it.

### Cable

The fastest link. Annex uses it by itself when one is plugged in.

1. Mac to Mac: connect a Thunderbolt or USB4 cable.
2. Anything else: connect an Ethernet cable, with a USB-C adapter if needed.
3. Connect as usual. The link shows as `Cable`.

Note: A plain USB charging or data cable isn't a network link, so it doesn't work.

### Direct Wi-Fi

The Windows PC runs its hotspot and the other computer joins it: no router in between.

1. Set up Mobile hotspot once in Windows Settings.
2. Turn on `Use direct Wi-Fi` before connecting, or `Switch to direct Wi-Fi` during a session.
3. Annex joins the hotspot and reconnects by itself.

### Peer-to-peer Wi-Fi

Mac to Mac with no network at all, over the link AirDrop uses.

1. Keep `Peer-to-peer Wi-Fi` on in Settings (it is by default).
2. On a Mac you haven't paired yet, choose `Let a new Mac find this one` for 5 minutes.
3. It appears under `Nearby` on the other Mac as `Peer-to-peer`.

### Sound

Hear the computer you're viewing, and send your microphone back.

1. On the sharing computer, keep `Share this computer's sound` on.
2. On yours, keep `Hear the other computer` on.
3. For calls, turn on `Send my microphone`. On Linux it appears as `Annex Microphone`.

Note: Both computers need Annex 0.3.2 or later.

### Copy and paste

Copy on one computer, paste on the other, while you control it.

1. Keep `Share the clipboard` on in Settings.
2. Control the other computer, copy some text or a picture.
3. Paste it on your own computer, or the other way round.

Note: Passwords copied from password managers stay where they were copied.

### Send files

Drag files across; they arrive in the other computer's Downloads folder, checked.

1. Start dragging a file during a session.
2. Drop it on the island at the top of the screen (the notch on a Mac), or on the viewer window.
3. Use `Pause` or `Unsend` in the island while it sends.

### Scaling and refresh rate

Set the extended display like a real monitor: sharp, larger text, or 144 Hz.

1. Mac: choose `Extended display scaling` in Settings, or the resolution in System Settings → Displays.
2. Pick the refresh rate in System Settings → Displays → `Annex Display`.
3. Windows: use Settings → System → Display, as for any monitor.

### No one at this screen

Share a Raspberry Pi or Mac mini you only reach over SSH.

1. Turn on `No one at this screen`, or run `annex --headless --share` on Linux.
2. Turn on `Open at login` and `Start sharing when Annex opens`.
3. Read the PIN over SSH from `pairing-pin.txt` in Annex's data folder.

### Updates

Annex installs new versions for you, checked against a signature.

1. Open `About` and click `Check Now`.
2. Turn on `Receive beta updates` to try pre-releases early.
3. See `What's New` after each update.

### Logs for a bug report

Annex keeps a log on your computer. It never sends it anywhere.

1. Open `Developer` in Settings and click `Show Log Files`.
2. Reproduce the problem, then attach `annex.log` to an issue.

## Shortcuts

- `⌃ + ⌥ + ⇧ + Q`: Leave control of the other computer (Mac)
- `Ctrl + Alt + Shift + Q`: Leave control of the other computer (Windows and Linux)
- `Esc`: Leave a view-only session (Everywhere)
- `⌘ + ,`: Open Settings (Mac)
- `Return`: Connect to the selected computer (Nearby)
- `↑ / ↓`: Move between computers (Nearby)

## Troubleshooting

- **The other computer isn't under Nearby**: Same network, not guest Wi-Fi or a VPN? On Windows, allow the firewall and set the network to Private. On a Mac, allow Annex under Local Network. Or use `Connect by Code or Address…`.
- **It's listed but greyed out**: It isn't sharing yet: turn on sharing on that computer.
- **Extend Display is greyed out**: A sharing Windows PC needs the Extend-mode display driver, an option in its installer.
- **Black screen when viewing a Mac**: Allow Screen Recording for Annex in System Settings → Privacy & Security, then turn sharing off and on.
- **The mouse and keyboard do nothing**: The sharing computer must allow your device under `Paired Devices` (and a Mac needs Accessibility). Turn on `Control the other computer` on yours.
- **The PIN keeps failing**: After 5 wrong PINs, pairing pauses for 10 minutes. Type the PIN shown on the sharing computer.
- **The picture lags**: Use a cable or Direct Wi-Fi, or set `Quality` to `Fast (Wi-Fi)`.

Still stuck? [Open an issue](https://github.com/NRanjan-17/Annex/issues) with your `annex.log`.

## Uninstall

- macOS: `About` → `Uninstall…` removes the app, its key, paired devices, settings and permissions.
- Windows: Settings → Apps → Annex → Uninstall. It also removes the display driver, the firewall rule and all settings.
- Linux: `sudo apt remove annex`, then delete `~/.config/annex` and `~/.local/share/annex`.

## FAQ

### Does it cost anything?

No. Annex is free and open source under the MIT licence. There's no paid version and nothing to sign up for.

### Do both computers need Annex?

Yes: the one you're sitting at, and the one whose screen you want to use or extend.

### Can I use it over the internet?

Yes. On the sharing computer, get a code under This Mac or This PC, then type it on the other one. The screen goes straight between the two computers, encrypted.

### Will a plain USB cable work?

Only a cable that makes a network link: Thunderbolt or USB4 between Macs, or Ethernet (with an adapter if needed) for everything else.

### How sharp is the picture?

Up to 2560×1600 at 60 frames a second when mirroring, and Extend follows the other screen's refresh rate, up to 240 Hz. When both computers support HEVC the picture goes as HEVC, sharper at the same speed; otherwise H.264.

### What does Annex send to its servers?

On your own network, nothing. With an internet code, our server only swaps the two computers' addresses. If a network blocks a direct link, our relay passes the session on, still encrypted: nothing is stored or seen. The only other request is the update check to GitHub, which you can turn off.