SharpDesk on Linux

sharpdesk-agent turns a Linux box into a SharpDesk host. Sign in once with the same account as your other devices. On amd64 you can then view and control the box from SharpDesk. On Hyprland and Omarchy you can also Sharpen it for a third-party viewer.

Free for a limited timeThe Linux agent

The agent is a single static binary. On amd64, when the GStreamer libraries are installed, a second binary comes with it: sharpdesk-agent-host, which streams the screen so you can view the box in SharpDesk. No package manager and no sudo: everything lands under your own $HOME. Sign in with the same SharpDesk account as your other devices, and the box shows up in their machine lists.

Install

curl -fsSLO https://relay.sharpdesk.app/linux/dl/install-0.8.25.sh
echo "644d6d4018a03f162b2c562702a3637553ae78a72a9f65922843cddae2041a20  install-0.8.25.sh" | sha256sum -c && sh install-0.8.25.sh

Download first, check it, then run it β€” nothing executes until the digest matches. install-0.8.25.sh is written once and never rewritten (the release script refuses to reuse a versioned name), so that SHA-256 identifies exactly one file for good. It installs agent 0.8.25 and nothing else: the SHA-256 of each architecture's binary is written inside it, so nothing it runs depends on what the server says at install time. Verify the installer and you have transitively verified the binary it installs.

This detects your architecture and downloads the release to ~/.local/bin/sharpdesk-agent. On amd64 it also fetches sharpdesk-agent-host when the GStreamer, Wayland and xkbcommon libraries are present, and keeps it only if it runs on this machine. It prints This machine can serve Connect (screen sharing). when it does. If you're running it in a real terminal, it then walks you through the two steps that follow, prompting Sign in now? and then Install as a background service (systemd --user)?. Piped into a script with no terminal attached, it skips the prompts and just prints the two commands for you to run yourself.

πŸ“ŒThere is also an unversioned install.sh that always installs whatever the current release is. It is there for automation that deliberately wants the moving target β€” but because its contents change, no digest can be published for it ahead of time, so nothing about what it will do can be checked before it runs. Prefer the pinned command above.

Signing in stores a device credential under ~/.config/sharpdesk/. Installing writes a systemd --user unit (sharpdesk.service), enables it, and turns on loginctl linger, so hosting starts on boot and keeps running without an interactive login.

πŸ”„Installs keep themselves current β€” signed, checksum-verified, and never mid-session. See Staying current.

Requirements

The agent needs a running graphical session, and what it can do depends on which one it finds and on the CPU.

Hyprland (incl. Omarchy)View and control in SharpDesk on amd64. Sharpen with a third-party viewer, in Extend or Mirror, on amd64 and arm64. Detected by HYPRLAND_INSTANCE_SIGNATURE and hyprctl.
XorgView and control in SharpDesk on amd64. No Sharpen: Xorg can't create a virtual display, so the agent tells SharpDesk it can't sharpen and the option isn't offered. Detected by DISPLAY and xrandr.
arm64Only the static agent is published, so there is no picture in SharpDesk. Sharpen still works on Hyprland.

Other desktops, such as GNOME on Wayland, are not supported yet.

Everything the agent does on Hyprland is runtime-only: applied through hyprctl at session time, never written to your Hyprland config files. A reboot β€” or just ending the session β€” leaves you with exactly what you configured yourself.

To see what this machine can do:

sharpdesk-agent status

It reports your sign-in state, which backend (if any) was detected, whether virtual displays are supported here, and whether the systemd service is running. sharpdesk-agent-host --version ends in (host); if that file isn't in ~/.local/bin, this box can't stream its screen.

⚠️If neither backend is found the agent refuses to start rather than half-work, and says so plainly: β€œNo display backend found β€” needs an active X11 session (xrandr) or Hyprland (hyprctl).”

Staying current

The agent updates itself. It checks once at startup and then every 24 hours, give or take an hour β€” the interval is jittered on purpose, so a fleet that all installed together doesn't keep hitting the CDN in lockstep forever.

A check fetches a small JSON manifest (/linux/latest) listing each architecture's binary, its SHA-256, and its signature. Five things must hold before anything is swapped, and any one of them failing means no update:

NewerThe manifest's version is actually ahead of the running one.
YoursThere's a binary for this architecture β€” linux-amd64 or linux-arm64.
IdleNo session is in progress. A live session defers the update to the next cycle rather than pulling the display out from under it.
IntactThe downloaded bytes hash to the SHA-256 the manifest claims.
SignedAn ed25519 signature verifies over the version and the bytes together.

Why the signature covers the version too. Signing only the bytes proves they came from us but says nothing about which release they are β€” so a genuine, correctly-signed 0.7.2 could be re-served under a manifest claiming to be 0.7.4, and every check would pass while quietly rolling you backwards into whatever that older build's bugs were. Binding the version into the signed payload makes that relabel fail verification outright. An older-style signature that covers only the bytes is refused rather than accepted as a fallback.

The public half of the signing key is compiled into the agent; the private half never leaves 1Password and is piped straight into the signer while a release is cut, so it touches no disk, no argument list, and no repository.

The swap can't leave you with half a binary. The new build is written alongside the old one in the same directory β€” deliberately, so the rename that follows stays on one filesystem and is therefore atomic β€” marked executable, and only then renamed over the original. A partial download, a full disk or a power cut can never produce a running agent that is half of two versions: nothing but a completed rename ever changes what the path points at. The agent then exits, and systemd starts the new binary.

πŸ›ŸAn update that lands while a session is somehow still live restores your display before it exits. Otherwise the replacement process would start up with the viewer's resolution already applied, take that for your normal arrangement, and later “restore” you to it.

A failed check is never fatal β€” it prints why and carries on hosting. sharpdesk-agent update forces a check immediately, and sharpdesk-agent config set autoUpdate false stops the automatic ones for good.

Removing it

systemctl --user disable --now sharpdesk
rm -f ~/.local/bin/sharpdesk-agent* ~/.config/systemd/user/sharpdesk.service
rm -rf ~/.config/sharpdesk ~/.local/state/sharpdesk
systemctl --user daemon-reload

amd64View it in SharpDesk

With sharpdesk-agent-host installed and the service running, the box can be viewed and controlled from SharpDesk on your other devices, the same way as a Mac: you see its screen and use its pointer and keyboard.

What it needs

An amd64 machine, a native Wayland or Xorg session, and GStreamer with a video encoder. On Arch and Omarchy:

sudo pacman -S --needed gst-plugin-va gst-plugins-ugly gst-plugins-bad \
                        pipewire xdg-desktop-portal-hyprland
gst-plugin-vaHardware H.264 and HEVC encoding through VA-API.
gst-plugins-uglyx264enc, the software encoder used when there is no hardware one.
gst-plugins-badThe H.264 and HEVC parsers. Required.
pipewire, xdg-desktop-portal-hyprlandScreen capture on Wayland. Already on Omarchy.

On Debian and Ubuntu the GStreamer packages are gstreamer1.0-plugins-good, -bad and -ugly, gstreamer1.0-x and gstreamer1.0-vaapi.

Install them before you run the installer, so it picks up the host binary. If you add them later, run the pinned installer again, then sharpdesk-agent install so the service starts the host binary.

The first connection

On Wayland the agent asks for the screen through the desktop's screen-sharing portal. The first time you connect, a dialog on the Linux box asks which screen to share, and someone at the box has 45 seconds to answer it. The agent keeps the portal's answer, so later connections normally start without the dialog.

On Xorg there is no dialog. The agent captures the local display its session runs on.

What works

If SharpDesk shows no way to connect to the box, look in the journal. When the agent starts and can't stream, it writes this machine cannot serve Connect: followed by the reason.

journalctl --user -u sharpdesk -n 50 | grep "cannot serve"

Hyprland Β· OmarchySharpen with your own viewer

Sharpen resizes the box's display to fit a third-party viewer's window, such as a VNC client, and SharpDesk shows nothing itself. It needs Hyprland, which includes Omarchy, on amd64 or arm64. An Xorg box isn't offered Sharpen.

In SharpDesk for Mac, press Sharpen on the box's page. On a box that can also be viewed in SharpDesk, that button is Connect, and Sharpen is Sharpen only (for another viewer app) in its Β·Β·Β· menu. Then connect your viewer to the box as usual. See Sharpen with your own viewer in the setup guide for sizing and auto-sharpen.

There are two arrangements, Extend and Mirror. While a session runs, the Mac shows them as Arrangement in Machine Settings…. The URL API takes mode=mirror, and so does the command line.

Extend β€” a display that wasn't there before

On Hyprland, Extend doesn't touch your real monitor at all. The agent creates a brand-new virtual output at whatever size the viewer asks for, and that's what the remote session sees. Your physical display keeps running exactly as configured.

The virtual output has no EDID to negotiate with, so it can be any size β€” including well past anything your real hardware would ever advertise. That's what makes it useful behind capture hardware β€” a PiKVM, a capture card β€” that caps the real output's mode list.

Mirror β€” the same desktop, both screens

On Hyprland, Mirror is Mac-style. The session drives a virtual display at whatever resolution the viewer asks for, and every enabled physical output is pointed at it using Hyprland's own monitor mirroring: the same desktop on both, full resolution for the remote viewer, scaled to fit on the panel. Your panel's EDID isn't the ceiling here either β€” the size the viewer asks for is the size the session runs at.

When the two aspect ratios don't match, which is normal when your Mac is matching a window, the panel letterboxes: black bars, never a stretch.

Restore

Restore is automatic. Disconnecting, signing out, or killing the process (SIGTERM/SIGINT) puts back whatever was live before the session started: the resolution that was set before the first Mirror sharpen, the mirror cleared from every physical output, any virtual output the session created destroyed, and the workspaces the mirror pushed aside moved back where they came from. Only those β€” anything you deliberately keep on the virtual display (see Display modes) is left exactly where you put it.

Nothing is ever written to your Hyprland config either, so anything a session might leave behind is reverted by a compositor restart or a reboot anyway.

πŸ’‘If the agent itself dies mid-session, the mirror is cleared within seconds of it coming back β€” but workspaces that were evacuated stay where they are. Drag them back.

No Blackout. SharpDesk doesn't offer Blackout for a Linux box: there's no spare screen to blank instead of the one you're using. If the flag arrives anyway, from the URL API for example, the agent ignores it rather than failing the session.

Display modes

Two ways the virtual display can live. Hyprland only.

display sessionThe default. The virtual display is created when a session starts and destroyed when it ends. Between sessions, nothing exists.
display alwaysThe virtual display exists from the moment hosting starts β€” parked at 1280Γ—720 when idle, resized in place by sessions. The output keeps the name sharpdesk throughout, so a capture tool, recorder or VNC server can bind it once and stay bound.
sharpdesk-agent config set display always

A parked display is still a real second monitor, so one workspace will live on it. The agent parks it far away from your real screens, sharing no edge with them, so your mouse can't wander onto an invisible monitor; sessions bring it back to normal adjacency while they run.

πŸ’‘If a stray workspace living on the parked display bothers you, pin your workspaces to your physical output in your Hyprland config.

OptionalYour own VNC, alongside SharpDesk

You don't need VNC to see a Linux box: on amd64 you can view it in SharpDesk. A VNC server is still useful as the third-party viewer for Sharpen, or on arm64, where there is no picture in SharpDesk.

SharpDesk stopped managing a VNC server in 0.8.5, so the wayvnc and wayvncPort settings are gone. config unset wayvnc clears the stale key from a box that upgraded, and a config that still carries it loads fine. Since the agent no longer runs one, nothing of SharpDesk's competes with your own wayvnc for a port or a control socket.

A systemd --user unit at ~/.config/systemd/user/wayvnc-desktop.service:

[Unit]
Description=wayvnc on the physical display
After=graphical-session.target
PartOf=graphical-session.target

[Service]
Type=simple
ExecStart=/usr/bin/wayvnc -g -r -o eDP-1 100.x.y.z 5901
# wayvnc ignores SIGTERM; without this, every stop waits out the timeout.
KillSignal=SIGKILL
Restart=on-failure

[Install]
WantedBy=graphical-session.target

Swap eDP-1 for your own output name and 100.x.y.z for this machine's Tailscale address (tailscale ip -4). Then systemctl --user daemon-reload and systemctl --user enable --now wayvnc-desktop.

⚠️One catch: while a Mirror session is live, the mirroring panel disappears from the Wayland client world entirely, so a wayvnc bound to it is serving nothing (see Known caveats). Pause it for the duration with the session hooks below.
sharpdesk-agent config set onSessionStart \
  'if [ "$SHARPDESK_MODE" = mirror ]; then systemctl --user stop wayvnc-desktop; fi'

sharpdesk-agent config set onSessionEnd 'systemctl --user start wayvnc-desktop'

Only the start hook tests the mode β€” Extend sessions never need the pause, since your physical output carries on exactly as it was throughout. The end hook runs unconditionally on purpose: starting a unit that's already running does nothing, and that way nothing can leave your desktop VNC stopped.

Session hooks & the status feed

Two seams for everything that isn't SharpDesk. Hooks are the write side: run something when a session starts or ends. The status feed is the read side: look at what's happening right now.

onSessionStart / onSessionEnd / onModeChange

Shell commands, run by /bin/sh at session boundaries (and, for onModeChange, when a live session switches between Extend and Mirror) with the session's details in the environment.

SHARPDESK_PHASEThe session phase β€” idle, applying, active, restoring or failed.
SHARPDESK_MODEextend or mirror.
SHARPDESK_PREVIOUS_MODEFor onModeChange only: the mode before the switch.
SHARPDESK_WIDTH
SHARPDESK_HEIGHT
SHARPDESK_SCALE
The geometry the session applied.
SHARPDESK_OUTPUTThe virtual output's name, when the session has one.
SHARPDESK_PEERThe name of the device that started the session.
⚠️Always quote "$SHARPDESK_PEER". It is peer-supplied text β€” a device name somebody else chose β€” and an unquoted expansion inside a shell command is exactly the wrong place for it.
sharpdesk-agent config set onSessionStart \
  'logger -t sharpdesk "$SHARPDESK_PEER: ${SHARPDESK_WIDTH}x${SHARPDESK_HEIGHT}"'

Hooks are supervised but never fatal: the agent journals when one starts and what it exited with, and a hook that fails or hangs can't take the session down with it. A long-running hook is fine β€” a capture tool held open for the session's lifetime is the whole idea.

The status feed

The agent writes ~/.local/state/sharpdesk/status.json: the phase, the peer device, the applied resolution and scale, the mode, and when the session started.

updatedAt is a heartbeat, not just a change marker β€” the file is rewritten at least every 30 seconds even when nothing is happening. So a reader can tell β€œquiet” from β€œdead”: if updatedAt is older than that, the agent isn't running.

The same feed drives the terminal's live view:

sharpdesk-agent status --watch

The Omarchy bar widget reads it too.

Configuration

sharpdesk-agent config prints the effective configuration. config set <key> <value> and config unset <key> edit ~/.config/sharpdesk/config.json; keys the agent doesn't recognise are left alone.

scaleclient (default) β€” virtual displays follow the viewer's scale, so a Retina Mac gets a 2Γ— HiDPI display automatically. Or pin 1–3 for β€œthis box is always 2×”.
displaysession (default) or always. See Display modes.
wayvnc, wayvncPortRetired in 0.8.5. config set refuses them; config unset still clears a stale key. See VNC.
onSessionStart
onSessionEnd
onModeChange
Shell commands run at session boundaries, with SHARPDESK_* in the environment. See Session hooks.
notificationson (default) or off β€” desktop toasts when a session starts and ends.
outputWhich physical output to drive. The first connected one, unless you name another.
allowTerminalfalse (default). Set true to let your other signed-in devices open a terminal on this box. The shell runs as the agent's user. On a Mac or an iPhone, you confirm it's you before one opens. Setting this back to false closes an open shell within a second.
verboseLoggingfalse (default). Set true for more detail in the journal when something needs debugging.
autoUpdatetrue (default). Set false to stop the agent updating itself.
baseURLThe relay the agent talks to. Leave it alone unless you've been told otherwise.
πŸ’‘Everything above output takes effect at the next session, with no restart. output, autoUpdate and baseURL are read when the service starts β€” run systemctl --user restart sharpdesk after changing those.

Controlling other machines

The same binary works in both directions. A Linux box that can be sharpened can also do the sharpening β€” to a Mac, or to another Linux box β€” with no second install and no separate sign-in. One device registration, one identity, both roles.

From the command line

sharpdesk-agent hosts                              # what's on this account
sharpdesk-agent sharpen mac-mini --size 2560x1440  # resize it
sharpdesk-agent sharpen mac-mini --match-window    # ...to the focused window's size
sharpdesk-agent restore mac-mini                   # put it back

The machine is named by device id, exact name, or a unique case-insensitive prefix β€” sharpen plex is enough when only one machine starts with “plex”. A prefix matching two machines is an error listing both, never a silent pick, and the box refuses to target itself.

--size W×HThe size to apply, e.g. --size 2560x1440.
--match-windowUse the currently focused window's size instead, measured once, when you run the command. The target does not follow the window afterwards. Needs a running Hyprland session on this box.
--modeextend (default) or mirror. Same meanings as above β€” but they describe what the target does.
--scale1–3, default 1. Density belongs to the machine being controlled β€” that's what its own scale setting is for β€” so a scale invented here would quietly override its choice.

Sizes are validated against the target's own limits before anything goes over the network, so an impossible size costs no round trip and tells you why. Neither sizing flag is an error rather than a guessed default: the size a machine ends up at should be one somebody asked for.

⏳The target keeps the new size until you run restore, it goes offline, or the eight-hour session ceiling expires. Exit codes: 0 done, 1 the target refused or wasn't reachable, 2 a problem with the command or this machine's sign-in.

A machine-readable roster

sharpdesk-agent hosts --json

The same roster as JSON, for anything that has to parse it. It exists because device names contain spaces and parentheses β€” “iPad Pro 11-inch (M5)” β€” so the column layout that reads well in a terminal cannot be split reliably.

Each entry adds two fields the human listing implies but doesn't state: isSelf, and canHost β€” whether the machine can be sharpened at all. Phones and tablets run the SharpDesk controller and have published keys, so nothing further down the stack would stop a list from offering them, but they can't host a display. Deciding that once, here, keeps every caller from inventing its own answer.

From the Omarchy panel

πŸ“¦The bar widget is on GitHub. Everything above also works from any terminal.

The plugin's panel has a CONTROL section listing every machine on the account that can be sharpened. Pick a Size and a Mode, then use the two buttons on a machine's row: sharpen it, or hand its displays back. Size and Mode apply to the next action and reset to Match window and Extend each time the panel opens, so yesterday's choice never silently applies to today's machine.

The panel is deliberately stateless. It offers the two verbs and reports what the far machine said back; it never claims to know whether a session is currently yours, because a one-shot command keeps no such record β€” a session can end from the other side, expire at the eight-hour cap, or be taken over by another device.

It also keeps working when this box's own sharpdesk-agent service isn't running: controlling other machines talks to your account, not to the local agent. What it needs is a signed-in box.

⚠️Extend needs Hyprland on the target. Point it at a headless server and the sharpen is refused β€” with that machine's own sentence, relayed to you unchanged, telling you to use Mirror instead.

Known caveats

Three things worth knowing before they surprise you.

A mirroring panel is invisible to screenshot tools

While a Mirror session is live, the physical output disappears from the Wayland client world β€” grim and anything else that enumerates outputs simply won't find it. Local screenshot and capture tools can't see the panel until the session ends. If you need capture during a session, capture the virtual display instead; display always keeps it there for exactly this.

Switching Extend β†’ Mirror mid-session can crash the Omarchy shell

Switching a live session from Extend to Mirror can currently take the Omarchy shell down with it. It's an upstream Quickshell issue and is being reported. Until it's fixed, restore the session and sharpen straight into Mirror rather than switching modes while one is running.

Whole-layout capture sees a huge canvas under display always

The parked display sits deliberately far away from your physical screens, which means anything capturing the whole layout rather than one named output sees an enormous, mostly-empty canvas. Bind the specific output you want.

Stuck? Write to [email protected] β€” a human reads it.