User manual

Install one app on each machine, sign in with the same email everywhere, and your machines find each other. This manual covers the current apps for Mac, Windows, Linux, iPhone and iPad, from the first sign-in to sharing a machine with someone for an hour.

Written for the November 2026 betas: Mac 0.4.56, Windows and Linux 0.8.49, iOS 0.2.26. Where a platform does something differently, it says so. Older builds won't have everything here, and much of it is new, so tell us if anything doesn't match what you see.

Step 1Install

Which app goes on a machine depends on whether you sit at it or only reach it.

A Mac you useSharpDesk for Mac. View and control your other machines from it. It can host too. Download
A Mac you only reachSharpDesk Host for Mac. Hosting only. Download
A PC you useSharpDesk for Windows. Views and hosts. Download
A PC you only reachSharpDesk Host for Windows. Hosting only. Download
A Linux boxThe Linux agent, installed from a terminal. Hosting only. See SharpDesk on Linux.
iPhone and iPadA viewer only. Access is by request for now: write to [email protected].

The Mac apps need macOS 15 or later on an Apple Silicon Mac. The Windows apps need 64-bit Windows 10 or later on an Intel or AMD PC; see Windows notes for the SmartScreen prompt. SharpDesk is free for a limited time.

Step 2Sign in

  1. Open the app and enter your email. A 6-digit code arrives from [email protected].
  2. Enter the code. This machine joins your account.
  3. Do the same on every machine, with the same email. Each machine then appears in the others' lists.
  4. On a Mac, PC, iPhone or iPad, approve the new device from one you already use.

There are no passwords, IP addresses or ports. On a Mac, iPhone or iPad you can add a passkey after the first sign-in, so later sign-ins don't need an email.

After the first sign-in, a Mac opens Set Up SharpDesk (Set Up SharpDesk Host in the Host app) and asks for:

Local Network and Available Before Sign-In are optional. You can change all of them later in System Settings.

Step 3Approve a new device

Your account keeps a list of the devices you trust. A new Mac, PC, iPhone or iPad joins that list only when a device already on it approves it. This stops someone who gets into your email from quietly adding their own computer.

On the new device

After sign-in it shows Approve this device from one of your other devices, with a six-digit code (for example 482 913) and a QR code.

On a device you already use

MacApprove a Device… in the menu bar panel's footer or the app menu, or Settings → Account → Devices → Approve a Device…. Scan a QR Code… uses the camera instead of typing.
iPhone and iPadSettings → Account → Devices → Approve a device…, or scan the QR code.
WindowsApprove a device… in the machines window. Enter the six-digit code.

Check the name it shows, such as Approve “Reception PC” (Windows)?, then choose Approve. That device can now connect to every machine on your account.

Each code works once. If it's typed wrongly, the new device shows a fresh code; use that one.

A device already on your list that lost its security key, say after a reinstall, goes through the same steps. You'll see “name” lost its key. Approve its new one? Only say yes if that is really your device: it replaces the old key, and a device still using the old one stops working.

Machines that only host

SharpDesk Host on a Mac or PC, and the Linux agent, don't need a code. They prove who they are when they sign in, and the next time one of your Macs, PCs, iPhones or iPads is online it adds them by itself. Activity shows Added host name when that happens.

While approval is being rolled out, a device that isn't approved yet still works. You'll see it marked Not approved, and the iPhone app offers Use SharpDesk for now. Approve it anyway: a later update will turn unapproved devices away. Devices that signed in before approval existed show an Approve… button in the Devices list, which approves them without a code.

Step 4Connect to a machine

In SharpDesk for Mac, open the Machines window, select a machine and press Connect (⌘↩). Double-clicking a machine in the list does the same, and the menu-bar panel has a Connect button on each row.

The machine's picture opens in its own window, and you use it with your own pointer and keyboard. To end the session, choose Disconnect (⇧⌘E) or close the window.

On Windows, click Connect on the machine's card. On iPhone and iPad, tap the machine, then Connect. Linux boxes can be viewed on amd64; see View a Linux box in SharpDesk.

If the machine asks before letting anyone in (see Ask before connecting), you'll see Asking machine for permission… until someone there answers. If the toolbar says View only (set on the machine), that machine has Allow control turned off: you can watch, but not click or type.

Picking a display

Each machine's page has a Next session section, folded until you open it. Its Display choice sets what Connect shows:

Sharpened displayA display made on the host to fit your window exactly. Where the host can make one (a Mac, or a PC with SharpDesk's display driver), this is where Connect starts.
Real screenThe machine's own screen, as it is. A Linux box always starts here.
Each screen by nameListed when the machine has two or more screens.

Arrangement (Your default, Extend or Mirror) applies to a sharpened display: Extend adds it beside the host's own screens; Mirror shows the same desktop on them.

During a session, Display in the viewer's toolbar switches between the sharpened display, the machine's own screen, or a single screen. It appears when the host has two or more screens.

The toolbar also has Control (⇧⌘C) to turn your pointer and keyboard on or off, Blackout (⇧⌘B, Mac hosts only) to darken the host's own displays while you view it, and Full Screen. Hide Bar (⌥⌘T) in the View menu hides the toolbar. Anything not on the bar is under More, along with Customise Toolbar….

Keyboard and pointer

While your pointer is inside the picture and Control is on, every key goes to the far machine, including ⌘Tab, ⌘Space, ⌘W and ⌘Q. Media keys stay on your Mac. Move the pointer out of the picture to get your keyboard back.

The first time you type in a session, macOS needs to let SharpDesk see those shortcuts. A banner asks you to allow SharpDesk in Input Monitoring; click Grant….

If the Mac viewer's Keyboard button turns into an orange warning triangle, another app on your Mac is holding Secure Input, usually a password field. The button names the app; close that field and your shortcuts come back.

Shortcuts… in the More menu lets you remap keys for one machine.

Sound

Mac and Windows hosts send sound; Linux hosts don't. Turn it on with Sound in the toolbar; it starts off on a Mac viewer. To have it on by default for a machine, use the Sound switch in its Next session section. A Windows host goes silent while it's locked or at its sign-in screen.

FileVault restarts

A Mac with FileVault normally stops at the disk password after a restart, where SharpDesk can't reach it. If you choose to, you can save that password on the Mac in Settings → This Mac → FileVault restart recovery, so a restart comes back to the normal login window. Then, while connected, choose Arm FileVault Recovery from the Machine menu before you restart it.

This reduces FileVault's protection: someone who steals the Mac and restarts it reaches the login window instead of the disk password. Only use it on a Mac you physically trust. A cold power loss still asks for the FileVault password.

Wake a sleeping machine

An offline machine offers Wake: in the ··· menu of its page on a Mac, as a button on its page on iPhone and iPad, and in the card's menu on Windows. Another of your machines on the same network sends the wake signal, and SharpDesk watches for 90 seconds for it to come back. If more than one could do it, you choose with Wake using.

It needs another machine on your account that is on and on the same network. The sleeping machine must have Wake on LAN turned on, and must have been online with SharpDesk at least once so SharpDesk knows how to reach it.

Record a session

Record saves what you see to a video file on the device you're viewing from. It's video only, with no sound, and the machine you're viewing is not told. Use Stop Recording to finish.

MacMore in the toolbar. A red dot shows while it records. Saved in Movies/SharpDesk.
WindowsThe viewer's bar. Saved in Videos\SharpDesk.
iPhone and iPadThe More sheet. Saved in the app's Recordings folder.

Send files and the clipboard

Sharing the clipboard and sending files need two switches, and both start off: one on the machine being reached, and one on the device you connect from. A machine that shares its clipboard also accepts files.

Mac hostSettings → This Mac → Share the clipboard and files. Files land in your home folder, in SharpDesk. Macs set up before October keep the setting they had.
Windows hostShare the clipboard and files in the tray menu, the SharpDesk Host window, or the This PC button at the top of SharpDesk for Windows. Files land in Downloads\SharpDesk.
Linux hostNo clipboard, and it doesn't receive files. It can send them to you (below).

On the device you view from, turn on Share clipboard and files with this machine on the machine's page (Mac and iPhone/iPad), or Share Clipboard and Files in the viewer's toolbar (Share Clipboard on Windows). If the host's own switch is off, it says so and names the switch to turn on there.

On a Mac, send files by dragging them onto the viewer window, or with Send Files… in the toolbar's More menu. Files only, not folders. The confirmation says where they were saved. Anything your password manager marks as concealed is never copied across. Then send files by dragging them onto the viewer window, or with Send Files… in the toolbar's More menu. Files only, not folders.

The Windows viewer sends files too, with Send files… or by dragging them onto the window.

Files from the machine you're viewing

The person at a machine can send files to you while you're connected. Turn on Allow incoming files on the device you view from first; it's off by default, and nothing is ever opened for you.

Mac viewerSettings → Sessions → Files from computers you view. Saved in SharpDesk/Incoming in your home folder.
iPhone and iPadIn Settings. Saved in the Files app, in SharpDesk ▸ Incoming.
Windows viewerSettings, Turn on incoming files. Saved in Downloads\SharpDesk\Incoming.

To send, on a Mac host use the Send Files… strip in the menu-bar panel; on a Windows host, Send Files… in the SharpDesk Host window; on Linux, sharpdesk-agent send file. These appear only while someone is viewing. If the viewer's switch is off, the sender sees They haven't turned on Allow incoming files.

Terminal

You can open a command line on a host. It runs as that host's user. It is off on every host until you turn it on there:

Mac hostSettings → This Mac → Allow Terminal.
Windows hostAllow Terminal in the SharpDesk Host window, or under This PC in SharpDesk for Windows.
Linux hostsharpdesk-agent config set allowTerminal true. See Linux configuration.

On the Mac, choose Terminal… (⌃⌘T) from the Machine menu or the machine's ··· menu. It asks for Touch ID, or your login password on a Mac without Touch ID, before it opens. The item is greyed out for a host that hasn't allowed it.

Chat

While someone is connected, the two of you can send short text messages. In a viewer, use Chat in the bar; it shows a badge when there's something unread. Sent messages are marked Delivered once they've shown on the other side.

On a Mac host, a message appears in the menu-bar panel with Reply; the person there can also start a chat with Message the viewer. On a Windows host, a notification offers a reply box, and the SharpDesk Host window can start a chat too. A message stays on screen until it's dealt with. A Linux host shows a desktop notification and can't reply.

Chat is never stored. Messages show on screen and nowhere else: not on SharpDesk's servers, not in Activity, not on either machine. They're gone when the session ends.

Sharing with peopleWhich way to share?

There are two ways to bring in someone who doesn't have a SharpDesk account. They look alike, because both use a 12-digit code, but they go in opposite directions.

Guest inviteQuick Connect
Use it toLet someone see one of your machinesSee and fix their computer
Who starts itYou, with Invite a guest…They download Quick Connect, and it shows a code
What gets sentYou send them a linkThey read you a code
What they needA web browser (or a SharpDesk app)The Quick Connect app on their Mac or PC
ControlView only unless you allow controlYou see and control their computer once they click Accept
ExampleShowing the practice manager the booking screenHelping a relative with their laptop

In this manual, a guest is always someone looking at your machine through an invite.

Guest invites (web link)

An invite lets someone without a SharpDesk account see one of your machines for a short time, from a web browser. You make a link and send it however you like (Messages, email). Normally the first person to open it is your guest and it can't be used again; you can also let up to three people use the same link.

Making an invite

  1. Find Invite a guest…:
    • Mac: the ··· menu on the machine's page, or the bottom of People in the viewer's toolbar while you're connected.
    • iPhone and iPad: on the machine's page, or in the viewer's More sheet while you're connected.
    • Windows: the machine card's ··· (More actions) menu.
  2. Choose the Kind:
    • Assist (the default): they can join only while you're connected to that machine, and they leave when you disconnect. Use this when you're working together.
    • Timed: they can stay for the whole session, even after you disconnect.
    A machine too old for Assist offers Timed only.
  3. Choose what they can do: View only (the default: they see the screen and can chat) or View and control (they can also use the mouse and keyboard). This choice is labelled Access on Mac and iPhone, and What they can do on Windows.
  4. If the machine can seat several people, choose Guests: 1, 2 or 3. Each guest uses the same link; one can control at a time and the others watch.
  5. Optionally fill in Who is it for?, such as “Mum” or “IT support”. The label shows on the machine while they're connected.
  6. Pick how long Link works for (10 minutes, or 5 minutes) and how long They can stay once they're in (30 minutes, 1 hour, 2 hours or 4 hours; 1 hour is the default). For Assist this is the longest they can stay.
  7. Choose Create Link. Send the link with Copy Link (or Share on iPhone), show them the QR code, or read out the 12 digits underneath for someone using Connect with Code… in a SharpDesk app.

The link looks like https://viewer.sharpdesk.app/#481203559170. The part after the # is the secret, and a browser never sends that part to any server, including SharpDesk's.

Your machine's page then lists the guest, for example Guest Mum · Waiting for the link to be opened · 7 min left · view only, and later Connected · 45 min left (or Connected · Until you disconnect · 45 min max for Assist).

One at a timeEach machine can have one open invite, which can seat up to three guests. End it to invite someone else.
Daily limitUp to 20 invites a day on your account.
Greyed out?The reason is shown underneath: the machine is offline, it needs a SharpDesk update before it can take guests, you need to sign in, or you need a licence or active trial. SharpDesk Host and the Linux agent can't make invites; make them from a Mac, PC, iPhone or iPad. A Linux machine can't be opened from a web browser yet. An invite to one works only for someone signed in to a SharpDesk app, using Connect with Code….

What your guest sees

  1. They open the link in a current Safari, Chrome, Edge or Firefox. A page explains that someone has sent them a SharpDesk invite. Nothing connects until they press Join, so a link preview in a chat app can't use the invite up.
  2. After Join, the page shows its progress. With an Assist invite, they can only get in while you're connected to the machine. If your machine asks before connecting, it says Waiting for someone at machine to allow this connection.
  3. The picture appears. The bar at the top has Control and Keyboard (only if control is allowed), Full Screen, Chat and Leave. When other people are connected it also has People, Request control and Release control; see People.

The picture in a browser is a little slower and softer than in the SharpDesk apps. It suits a short look or helping out, not a day's work.

What a guest can and can't do

A guest can see the screen, hear its sound if the browser supports it, and chat with you. With View and control they can also use the mouse and keyboard, but only if the machine's own Allow control is on: the machine always has the last word.

A guest can never copy and paste, send or receive files, open a terminal, change the screen size, type stored passwords, or update or restart the machine. There's no setting to allow these.

If the machine has Ask before letting someone connect on, it asks when the guest arrives: Guest Mum (web link) wants to see this Mac. You invited them with a link. Allow it? If nobody answers within 30 seconds, the guest isn't let in.

Ending an invite

Press End beside the guest on the machine's page (on Windows, in the Invite a guest… window). Their page says The owner ended this session, and the link can't be used again. If you're connected too, Remove guest in People ends one guest; theirs says Machine's owner ended your session. An Assist guest leaves a few seconds after the last of your devices disconnects. Otherwise the invite ends by itself when its time is up, and the guest can press Leave at any time.

The machine being viewed has no End button of its own for a running guest. End it from one of your devices, or don't let them in: with Ask before letting someone connect on, choose Deny.

People: more than one viewer

Up to four people can be connected to one machine at once: you, your other devices and your guests. They all see the same picture, and one at a time is in control. While you watch on a Mac, iPhone or iPad, the pointer of whoever is in control is drawn on your picture. Quick Connect stays one to one, and machines on older builds take one viewer at a time.

People in the viewer's bar lists who's there, such as Daniel's Mac (you) and Guest Ana (web link), and who is In control. On iPhone and iPad it's a section in the Controls sheet.

WatchingSomeone else is in control. The bar says Watching.
Request controlAsks whoever is in control. They see name asked for control. with Hand over and Not now. After 30 seconds it counts as Not now.
Take controlYour own devices only. On those, simply clicking or typing in the picture takes control. Moving the pointer doesn't. Guests always have to ask.
Hand over to…Gives control to someone you pick.
Release controlLets go, so nobody is in control until someone takes it.
Remove guestYour own devices only. Ends that person's session.

Activity keeps a record of control changing hands and of people being removed.

Quick Connect

Quick Connect lets you help someone who has no SharpDesk account, on their own Mac or PC.

  1. Send them to sharpdesk.app/quick.html. They download Quick Connect, open it, and read you the 12-digit code it shows.
  2. Choose Connect with Code…:
    • Mac: the Machine menu (⇧⌘K), the toolbar, or the menu-bar panel.
    • iPhone and iPad: the + menu on the machine list.
    • Windows: the gear (SharpDesk menu).
  3. Type the code and choose Connect. Their screen asks them to Accept, and you see Waiting for them to accept….
  4. Once they accept, you see and control their computer. Their screen says who is connected, with an End button they can press at any time.

A code works once and expires after a few minutes; Quick Connect shows a New Code button when it does. Connect with Code needs you to be signed in. The same box also takes a guest invite's 12 digits or whole link.

Machines you hostPermissions for your devices

Every machine you can connect to has a group of switches called Permissions for your devices. They decide what anyone who connects to that machine may do, and that includes your own devices and your guests.

MacSettings → This Mac, in SharpDesk and in SharpDesk Host.
WindowsThe SharpDesk Host window (open it from the tray icon), or the This PC button at the top of SharpDesk for Windows.
Linuxsharpdesk-agent config set …; see Linux configuration.
Allow controlOn by default. Off, people who connect can only watch. More below.
Share the clipboard and filesOff by default. See Files and clipboard.
Allow TerminalOff by default. See Terminal.
Allow updates and restarts from your devicesOn by default. Your devices can update SharpDesk on this machine and restart SharpDesk. They never restart the computer itself.
Ask before letting someone connectOff by default. On, someone at the machine has to click Allow. More below.

Allow control: view only

With Allow control off, a machine is view only. People can connect and see the screen, and nothing more on that machine changes: no clicks or typing, no Type Password or Ctrl-Alt-Del, no Sharpen, Blackout or screen-size changes, no FileVault recovery. Their toolbar says View only (set on the machine), and it updates straight away if you flip the switch during a session.

Terminal, clipboard and files have their own switches, so turn those off too if you want a machine that can only be watched.

This is different from the Control button in a viewer's toolbar, which only pauses your own pointer and keyboard. The machine's switch wins.

Ask before letting someone connect

Turn this on for a machine that has people sitting at it, such as a reception PC. Whenever anyone connects, including you from your own devices, the machine shows a box: Daniel's iPad wants to connect. Allow it? with Allow and Deny.

Only at certain times: on a Mac or PC, set When to Only between set hours and choose From and Until (09:00 to 18:00 to start with). Outside those hours your devices connect without asking. A session that started before the hours begin isn't cut off, but anything new it does will ask.

The hours use the machine's own clock, every day. To limit a Windows PC to certain days, run this from a Command Prompt:

"%ProgramFiles%\SharpDesk\sharpdesk-agent.exe" config set askBetweenHours "09:00-18:00 mon-fri"

Use always instead of the hours to ask every time again. Linux machines don't offer asking yet.

Who's connected right now

Activity

Activity lists who connected to which of your machines, and what changed on your account, for the last 90 days. It's on Mac under Settings → Account → View Activity…, and on iPhone, iPad and Windows under Settings → Account → Activity. Filter it to one machine with the machine picker.

It records connections (Reception PC connected to Mac mini, marked invite for a guest or one-off for Quick Connect) and account changes: devices added or removed, hosts added automatically, passkeys, email changes, invites made and ended, control changing hands, people removed from a session, and account resets. It never records what was on screen, what was typed, chat, or where anyone connected from.

If you see a device you don't recognise, use Revoke… on its row. That signs it out of your account straight away, and it has to sign in again by email to come back. A session it has open is ended within a minute.

Needs attention

When a machine has been offline for over a day, has a SharpDesk update waiting, has updates and restarts switched off, or its last update or restart failed, the machine list shows a Needs attention filter with a count. On Mac and iPhone/iPad, open it to select machines and choose Update… or Restart… for all of them at once. SharpDesk does three at a time and waits for anyone using a machine to finish first. The Mac sheet also has Email me when it goes offline for each machine.

Hosting settings on a Mac

Settings → This Mac, in both SharpDesk and SharpDesk Host, has the permissions above and these:

Keep awakeAutomatic (the default) keeps the Mac and its display awake while sharpened. Or choose Keep Mac awake or Keep Mac and display awake.
Available before sign-inHosts the macOS login window after you log out.
Discoverable to your devicesSharpDesk for Mac only. Turning it off ends existing sessions. SharpDesk Host is always discoverable.
UnsharpenEnds any session holding this Mac's screens, removes the sharpened display and puts your screen arrangement back. Hosting stays on. Also in the menu-bar panel while there is something to put back.

Your accountDevices and removing them

On a Mac, Settings → Account → Devices lists every device on your account as Approved, Not approved or Removed, and shows Waiting for approval beside one that is asking. On iPhone and iPad it's Settings → Account → Devices. On Windows, an unapproved machine has a Not approved badge on its card.

Passkeys

On a Mac, iPhone or iPad you can sign in with a passkey instead of waiting for an email code. After an email sign-in, SharpDesk offers once to Add a passkey. Manage them in Settings → Account → Passkeys with Add Passkey…, Rename… and Remove…. Adding one asks for an emailed code first, and you get an email whenever one is added. Passkeys sync to your other Apple devices through iCloud Keychain.

Removing a passkey doesn't sign any device out. Windows doesn't support passkeys; sign in there by email.

Changing your email

Settings → Account → Change Email… (Mac), Email (iPhone and iPad) or Change Email (Windows). Confirm it's you with a passkey or a code sent to your current address, then enter the new address and the code sent there. Your devices stay signed in, your passkeys keep working, and your old address is told about the change.

Signing in again every two years

A sign-in lasts two years. From 30 days before, the machine shows Sign in again before date to keep hosting working, and you get a reminder email. Choose Sign In (Sign In Again… on Windows) and enter the emailed code; nothing is signed out while you do. On Linux, run sharpdesk-agent login. If the date passes, the machine stops being reachable until someone signs in on it.

If you lose all your devices

Approvals come from your other devices, so losing every one of them needs a recovery step.

A passkey recovery takes effect at once and can't be cancelled; you get an email and an entry in Activity saying it happened.

Your own viewerSharpen with your own viewer

If you prefer another viewer app, such as Screens, Apple Screen Sharing or a VNC client, SharpDesk can still make the picture sharp. It resizes a display on the host to fit your viewer's window, follows as you resize it, and shows nothing itself. The picture stays in your viewer app.

Macs can be sharpened this way, and Linux boxes on Hyprland or Omarchy. PCs can't: their sharpened display is viewed in SharpDesk.

  1. In the Machines window, select the machine and choose Sharpen only (for another viewer app) from its ··· menu.
  2. Connect your viewer to that machine as usual. Open Viewer on the machine's page launches it for you, once SharpDesk knows the host's network name. The menu beside it chooses Screen Sharing (Apple), Screens or Custom URL…, a URL with a {host} placeholder for any other viewer.
  3. SharpDesk sizes the host's display to your viewer window. Closing the viewer hands the display back, unless you've chosen to keep it sharpened (below). To hand it back yourself, choose Unsharpen.

While it runs, Machine Settings… (⌘I) has the Arrangement (Extend or Mirror), Black out host display, and Restore Displays.

With Apple Screen Sharing, use Standard mode. High Performance mode makes its own virtual display, and macOS won't allow a second one.

Auto-sharpen when you connect a viewer

Settings → Sessions → Auto-sharpen when I connect a viewer. It is off by default. When it's on, SharpDesk watches for a viewer window pointed at one of your machines and sharpens that machine without you choosing it first.

Viewers it recognises: Screens, Apple Screen Sharing, RustDesk, Jump Desktop, VNC Viewer, Microsoft Remote Desktop, AnyDesk, TeamViewer and Parsec. Version suffixes such as “Screens 5” count too.

Which machineIt matches the viewer window's title against your machines' names, so Mac-Mini-UK.local finds “Mac mini UK”.
When it's unsureIf two machines could match the same title, it does nothing rather than guess. Give your machines distinct names, or sharpen by hand.
Per machineThe Auto-sharpen choice in a machine's Next session section overrides the setting: Always for this Mac or Never for this Mac.

Also in Settings → Sessions: Match display under For new sessions picks Automatic or an entire screen of yours to match. After another viewer app disconnects picks Restore the host's display or Keep sharpened for up to 8 hours.

Size and following

Under More settings on the machine's page, or in Next session on a machine set to Sharpen only (for another viewer app):

SizeMatch the window follows your viewer as you resize it. Fixed size holds a width and height you enter.
SharpnessAuto (viewer), or a fixed density from Standard (1×) to 3×, with Retina (2×) between.

Machine Settings… (⌘I) has the same Screen choice (Match the window or Fixed size) and Follows, which picks what is matched: the Frontmost window, an entire screen, or one window you name. Make this the default saves the choice for new sessions. If a session matched the wrong window, pin your viewer here.

The sharpdesk:// URL API

Anything that can open a URL, such as a Shortcut, a script or a launcher, can tell SharpDesk for Mac to sharpen a machine to an exact size.

Sharpen at a sizesharpdesk://apply?width=1512&height=982 (1 to 8192 each)
A specific machine…&host=Mac%20Mini: a device name (any case) or device id. Without it, the selected machine, or the only one online.
Options&scale=1 to 3 (default 2) · &mode=extend|mirror · &blackout=1|0. Without mode or blackout, the machine's remembered setting.
Restoresharpdesk://restore, with the same host parameter.

From a terminal: open "sharpdesk://apply?width=1512&height=982&host=Mac%20Mini". An invalid value rejects the whole command. SharpDesk Host ignores these URLs.

An apply from a URL stops window-following, since you've given the exact size. To follow the window again, choose Match the window under Screen in Machine Settings (SharpDesk 0.4.21 or later).

x64 · Windows 10 or laterWindows notes

Troubleshooting

The sign-in code doesn't arrive

Check spam for mail from [email protected], then use Resend. It unlocks 30 seconds after each use. Codes expire, so request a fresh one if in doubt.

I can't connect to a Linux box

Viewing a Linux box needs amd64, GStreamer and the agent's host binary. See View a Linux box in SharpDesk, which also says how to find the agent's own reason.

Keys go to the wrong machine

Keys go to the far machine while your pointer is inside the picture and Control is on. Move the pointer out to use your own Mac. If shortcuts like ⌘Tab stay on your Mac, allow SharpDesk in Input Monitoring.

Sharpen matched the wrong window

Open Machine Settings… (⌘I) and pin your viewer with Follows.

A Mac's screens look wrong after a session

On that Mac, open SharpDesk and choose Unsharpen (in the menu-bar panel, or Settings → This Mac → Screens). It puts the physical screens back and removes SharpDesk's virtual display, whatever state they are in.

“Virtual display unavailable: failed to create…”

Another virtual display already owns that Mac. In practice that is Apple Screen Sharing in High Performance mode, which runs its own. Switch that session to Standard mode, or disconnect it, and try again.

A new device says “Approve this device”

Open SharpDesk on a Mac, PC, iPhone or iPad you already use and choose Approve a device; see Approve a new device. If you have no other device, see If you lose all your devices.

I can see the screen but can't click or type

If the toolbar says View only (set on the machine), turn on Allow control on that machine. If it says Watching, someone else is in control; see People. Otherwise check the toolbar's Control button is on and your pointer is inside the picture.

It keeps saying “didn't accept the connection”

That machine has Ask before letting someone connect on, and nobody pressed Allow within 30 seconds. Ask someone there to watch for the box, or change its hours. After a Deny, wait a minute before trying again.

My guest's link doesn't work

A link works once, and only for the time you chose (5 or 10 minutes) until it's opened. If it was already used or has expired, their page says so: make a new one. If their browser is too old, ask them to use a current Safari, Chrome, Edge or Firefox; the link still works until it expires.

How the picture travels

SharpDesk finds the shortest route it can: across your own network if both machines are on it, directly over the internet if it can, or through SharpDesk's relay if nothing else works. Every route is encrypted end to end, so the relay can't see the picture. If a machine has Tailscale, SharpDesk uses that too. There's nothing to set up; the message no route is the only time SharpDesk suggests installing Tailscale.

Lite can't reach the remote Mac

Check that the two Macs can reach each other (same network, or VPN up), that BetterDisplay is running with its HTTP integration on, and that the URL uses port 55777.

What the messages mean

When a connection stops, SharpDesk says why in one sentence, with a button for the next step where there is one. The ones people ask about most:

It saysWhat it means, and what to do
Machine is offline.The machine isn't reachable: it's off, asleep, or has lost its internet. Try Wake or check its network; Connect comes back when it does.
Machine didn't accept the connection.It asks before letting people in, and nobody pressed Allow. See Ask before connecting.
Waiting for someone at machine to allow this connection.The machine is showing the Allow/Deny box. Someone there has 30 seconds.
View only (set on the machine)The machine has Allow control off. You can watch but not click or type.
Approve this device from one of your other devices.This device isn't on your account's list yet. See Approve a new device.
Another device is already controlling machine.Someone else is using a machine that takes one viewer at a time. Wait for them to finish, or ask them to disconnect.
Machine is not allowed to record its own screen.On that Mac, open System Settings → Privacy & Security → Screen Recording and turn SharpDesk on.
Machine is showing its lock screen or a security prompt.A Windows PC is at its lock screen or an administrator prompt. Wait a moment, or use Type Password to sign in.
Its own screen still works.The sharpened display couldn't be made this time. Connect to its own screen shows the machine's real screen instead.
Sign in again before date to keep hosting workingThe two-yearly sign-in is due. See Signing in again.
This device was removed from your account.Someone removed or revoked it. Sign in again by email, then have it approved.
There is no route between this network and machine's.Both networks block every way SharpDesk tries. Installing Tailscale on both machines gives them a route.
The owner ended this session. / Machine's owner ended your session. / This invite has expired.Seen by a guest. Ask the person who invited you for a new link.
This link has no room left.Everyone the link allows is already in. Ask for another.
Machine is being used right now.Seen by a guest when another connection has the machine and it can't seat them. Ask for a new link once they've finished.
Machine already has as many viewers as it can take.The machine is full. Wait for someone to leave.
Machine didn't come back within 90 seconds.Wake didn't work. Check it's plugged in and that Wake on LAN is on in its settings.

Words we use

MachineA Mac, PC or Linux box you can connect to. Also called a host.
DeviceAnything signed in to your account, including iPhones and iPads that only view.
ViewerThe app, window or browser page that shows another machine's screen.
ApproveAdding a new device to your account's trusted list from one you already use.
GuestSomeone without an account looking at one of your machines through an invite link.
Quick ConnectThe small app someone without an account runs so you can help them on their computer.
SharpenSharpDesk making a display on the machine that fits your window exactly, so text is crisp.
UnsharpenPutting the machine's own screens back the way they were.
Real screenThe machine's own screen, as it is, without sharpening.
View onlyYou can see the screen but not use the mouse or keyboard, because of a setting.
WatchingSomeone else is in control right now; you can ask for it.
RelaySharpDesk's server (the app just calls it that), which helps machines find each other and carries the picture when there's no shorter route. It can't see the picture.

No accountSharpDesk Lite

The two pieces

Lite is the do-it-yourself version for BetterDisplay users. It needs no account: a small app on your Mac drives BetterDisplay on the remote one, directly over your own network or a VPN such as Tailscale.

On the Mac you sit atSharpDesk Lite Client Helper. It watches your viewer window and sends the resize instructions. Download it.
On the remote MacBetterDisplay with its HTTP integration turned on.

Both Macs must be able to reach each other directly: the same network, or a VPN like Tailscale that gives the remote Mac a stable address.

Setting it up

  1. On the remote Mac, install BetterDisplay and turn on its HTTP integration in BetterDisplay's settings. The default port is 55777. Set an access token there if you want one; it is recommended outside your own network.
  2. On your Mac, open Lite Client Helper and add a host: pick the BetterDisplay backend and enter the URL, for example http://192.168.1.20:55777 on a LAN or http://<tailscale-ip>:55777 over Tailscale. Paste the token if you set one.
  3. Pick the remote screen to manage and the viewer window to match, choose Extend or Mirror, and connect your viewer as usual.
BetterDisplay's HTTP integration listens on the remote Mac. Keep it on a trusted network or behind a VPN, and use an access token.

Stuck? Write to [email protected]. A human reads it.