VeloAssist User Guide
Private remote access for your Macs
VeloAssist lets you see and control your Macs from another Mac, an iPad or an iPhone. This guide covers everything from installing VeloAssist Host to keeping your connections secure.
1. How VeloAssist works
VeloAssist has two apps:
- VeloAssist Host runs on each Mac you want to reach. It lives in the menu bar, shares the screen and accepts keyboard and pointer input from devices you have paired with it.
- VeloAssist is the app you control from, on a Mac, iPad or iPhone. It lists your machines, organises them into groups and opens sessions.
Your devices connect to each other directly and every connection is encrypted end to end. Your screen is never sent through a VeloAssist server. Each device has its own private key, and a device can connect to a Host only after you have paired the two.
Today VeloAssist connects on the same local network, or anywhere over Tailscale. Connecting across the internet without Tailscale is coming in a later version.
2. What you need
| App | Runs on |
|---|---|
| VeloAssist Host | A Mac with macOS 15 Sequoia or later, Apple silicon or Intel |
| VeloAssist | A Mac with macOS 15 or later, or an iPad or iPhone with iPadOS or iOS 18 or later |
Both devices need to be on the same network, or both signed in to the same Tailscale network.
3. Set up VeloAssist Host
Download and install
- On the Mac you want to reach, download VeloAssist Host from assist.velosec.au. The download is signed and notarised by Apple.
- Open the disk image and drag VeloAssist Host to Applications.
- Open VeloAssist Host from Applications. Its icon appears in the menu bar.
Grant permissions
macOS asks you to allow a few things. The Host's Permissions window (in its menu) shows what is still needed and opens the right page of System Settings.
- Local Network: allow it when asked, so your other devices can find this Mac.
- Screen Recording: in System Settings, Privacy & Security, Screen & System Audio Recording, turn on VeloAssist Host. macOS asks to quit and reopen the app; let it. The screen cannot be shared until it has reopened.
- Accessibility: in Privacy & Security, Accessibility, turn on VeloAssist Host. Without it you can see the screen but your keyboard and pointer do nothing.
- Keychain: if macOS asks VeloAssist Host to use its keychain, enter your Mac password and choose Always Allow. The Host keeps its private key and its list of paired devices there.
macOS 15 and later ask from time to time whether VeloAssist Host should keep recording the screen. Choose to allow it, or remote sessions stop showing the screen.
Keep it running
Turn on Open at login in the Host's menu so it starts with your Mac. A Mac can be reached only while someone is logged in and VeloAssist Host is running. Prevent the Mac from sleeping, or turn on Wake for network access in System Settings, Battery or Energy.
4. Pair a device
Pairing introduces a device to a Host once. Afterwards that device can connect whenever it is allowed to. Every pairing needs someone at the Host to approve it.
From a Mac or iPad, on the same network
- Open VeloAssist and choose Nearby in the sidebar. Macs running VeloAssist Host on this network appear there.
- Choose Pair on the Mac you want. You can pick a group for it now or later.
- Both screens show a 6-digit code. Check that the codes match.
- Choose Codes Match on your device and Confirm Pairing on the Host.
If the codes do not match, cancel on both. Someone may be trying to intercept the pairing.
From an iPhone or iPad, with the QR code
- On the Host, open its menu and choose Pair a device. A QR code appears. It changes every five minutes and after each use.
- In VeloAssist, tap the Scan QR Code button at the top of the sidebar and point the camera at the code.
- Choose Confirm Pairing on the Host.
Over Tailscale
5. Connect and control
Paired machines appear in your machine list with a green dot when they can be reached. To connect, double-click (or double-tap) a machine, or select it and choose Connect in the details pane.
A session starts in control mode, so your keyboard and pointer act on the remote Mac. Switch to Observe Only to watch without sending any input.
If the connection drops, VeloAssist tries to reconnect. The Host waits 15 seconds for you to come back, then ends the session.
6. Sessions on a Mac
Each session opens in its own window. Closing the window disconnects. The toolbar holds:
| Control | What it does |
|---|---|
| Control / Observe Only | Send keyboard and pointer input, or only watch. |
| Send Keys | Sends shortcuts your own Mac would otherwise catch: Force Quit, Switch App, Spotlight, Lock Screen and Screenshot. |
| Quality | Adaptive balances sharpness and speed, Fidelity favours sharp detail, Low bandwidth suits slow connections. |
| Statistics | Shows frame rate, bitrate, round-trip time and the connection in use. |
| Zoom Out, Actual Size, Zoom In | Show the remote screen pixel for pixel, then zoom from a quarter to four times. |
| Fit in Window | Scale the whole remote screen to the window. |
| Disconnect | End the session. |
7. Sessions on iPad and iPhone
A session fills the screen. The key bar along the bottom holds the controls; tap the arrow at its right end to hide it, and tap the arrow again to bring it back.
Touch
By default your screen works like a trackpad:
- Move one finger to move the pointer.
- Tap to click. Tap with two fingers to right-click.
- Rest your finger for half a second, then move it, to drag.
- Move two fingers to scroll.
Switch to direct touch in the key bar to click exactly where you touch instead. A connected trackpad or mouse always moves the pointer directly, and a connected keyboard types on the remote Mac.
The key bar
| Key | What it does |
|---|---|
| Keyboard | Shows or hides the on-screen keyboard. |
| Right-click | Right-clicks at the pointer. |
| Trackpad / direct | Switches how touch moves the pointer. |
| Esc, Tab, Copy, Paste | Sends those keys. Copy and Paste send ⌘C and ⌘V on the remote Mac. |
| Shift, Control, Option, Command | Hold the modifier for your next key or click. Tap again to release it. |
| Arrow keys, Return | Sends those keys. |
| Settings | Quality, scaling (Fit or 1:1), Observe Only and Statistics. |
| Red power key | Disconnects. |
| Arrow | Hides the key bar. |
8. Organise your machines
Groups
- Create a group with + next to Groups in the sidebar. Give it a name, icon and colour.
- Double-click a group to rename it, or use its menu to edit or delete it. Deleting a group keeps its machines.
- Drag groups to reorder them. Drag a machine card onto a group, or use the card's menu, to add it. A machine can be in several groups.
Smart groups
All Machines, Online, macOS, Windows and By Tag fill themselves from your machines.
Details, notes and tags
Select a machine to open its details. Rename it, add notes and tags, set its Tailscale address and check its Device ID. The Device ID matches the one in the Host's menu, so you can confirm you have the right Mac.
Views and search
Switch between grid and list with the toolbar control. On a Mac, the slider sets the card size. Search finds machines by name, notes or tags.
Last-screen thumbnails
Cards can show the last screen you saw on each machine. Turn this on or off in Settings, turn it off for a single machine in its details, or clear all thumbnails. Thumbnails stay on the device that took them and are never uploaded or synced.
Removing a machine from the controller is coming in a later version. To stop a device connecting, revoke it on the Host (see Manage the Host).
9. Connect over Tailscale
Tailscale joins your devices into a private network wherever they are. VeloAssist can use it to reach a Mac from anywhere.
- Install Tailscale on the Host Mac and on your device, and sign in to the same tailnet on both.
- On the Host, open its menu and choose Copy Tailscale Address.
- In VeloAssist, choose Tailscale in the sidebar, then + (Add Tailscale Device). Enter the address or the Mac's Tailscale name and choose Pair.
- Compare the 6-digit codes and confirm on both, as when pairing nearby. Someone needs to be at the Host to confirm.
For a Mac you have already paired, add its Tailscale address in its details instead. VeloAssist connects over the local network when the Mac is there, and over Tailscale when it is not.
Only Tailscale addresses (100.64.0.0 to 100.127.255.255, fd7a:115c:a1e0:: addresses and Tailscale names) are accepted here.
10. Manage the Host
Everything is in the Host's menu bar menu.
Paired devices
Lists every device that can connect, when it was paired and its last session. For each device you can set:
| Permission | Meaning |
|---|---|
| View | See the screen. |
| Control | Use the keyboard and pointer. |
| Clipboard, Files | Reserved for clipboard sharing and file transfer, which are coming in a later version. |
| Ask every time | Someone at the Mac must allow each session from this device. |
Revoke removes a device. It can no longer connect, and would have to pair again.
During a session
The menu bar icon changes and a notification appears when a session starts, so anyone at the Mac knows. End active session disconnects at once. Pause sharing stops the Host accepting any connections until you turn it off.
Activity log
Records every pairing and session: which device, when, from where and for how long. Entries are kept for 30 days on the Mac.
11. Security and privacy
- Direct and encrypted. Sessions run directly between your devices and are encrypted end to end. Screen contents never pass through VeloAssist servers.
- Keys stay on your devices. Each install creates its own private key, kept in the keychain and never exported or synced.
- Every new device is approved by a person at the Host, and a man in the middle would show up as mismatched codes.
- You control access per device on the Host, and can revoke any device at any time.
- You can see who connected in the Host's activity log, and a session is always shown on the Host's menu bar.
- Signed software. VeloAssist comes from the App Store and VeloAssist Host is signed by LV-223 Pty Ltd and notarised by Apple. Download the Host only from assist.velosec.au.
Treat the Host's QR code like a password while it is on screen, and never approve a pairing you did not start.
12. Troubleshooting
The Mac does not appear in Nearby
- Check that VeloAssist Host is running and Pause sharing is off.
- Check both devices are on the same network, and that VeloAssist is allowed Local Network access (on iPhone and iPad: Settings, Privacy & Security, Local Network).
- If the Mac's firewall asks whether VeloAssist Host may accept incoming connections, choose Allow.
The session connects but the screen stays black
- Turn on Screen Recording for VeloAssist Host, then quit and reopen it.
- Quit macOS Screen Sharing on the Host if a Screen Sharing session is open, then connect again.
I can see the screen but cannot control it
- Turn on Accessibility for VeloAssist Host.
- Check the device has the Control permission on the Host, and that you are not in Observe Only.
The Host keeps asking for keychain access
Enter your Mac password and choose Always Allow, not Allow.
A Tailscale device shows as offline
- Check Tailscale is connected on both devices.
- Check the address in the machine's details matches Copy Tailscale Address on the Host.
- Check VeloAssist Host is running on the Mac.
13. Remove VeloAssist
- Host: choose Quit VeloAssist Host from its menu and move it from Applications to the Bin. Remove it from Screen Recording and Accessibility in System Settings, Privacy & Security.
- VeloAssist: delete it like any other app. To stop a device connecting first, revoke it in the Host's Paired devices.
14. Get help
Email assist@velosec.au. To report a security issue, email the same address with "Security" in the subject.