Nine guides, and every command you need to run them

Guide 01 Install and first connection

One build per platform, one flow afterwards: save a machine, double click its tile.

Every build for every platform is on the same page. Pick the file that matches your machine from the latest release.

macOS

Open the DMG and drag the app to Applications. The build is signed with a Developer ID certificate and notarised by Apple, so it opens normally, and the binary is universal, so it runs natively on both Apple Silicon and Intel. You can check the notarisation yourself:

spctl -a -vv -t exec /Applications/DeskVNCViewer.app

Windows

The installer, the MSI and the app inside them are code signed, and Windows shows the publisher name as it asks to install. SmartScreen builds reputation from a certificate plus download volume, so on a first run it may show its own notice: choose More info, then Run anyway. Check a download against the checksum published with the release:

certutil -hashfile DeskVNCViewer_<version>_x64-setup.exe SHA256

Linux

sudo apt install ./DeskVNCViewer_<version>_amd64.deb      # Debian, Ubuntu
sudo dnf install ./DeskVNCViewer-<version>-1.x86_64.rpm   # Fedora, RHEL

chmod +x DeskVNCViewer_<version>_amd64.AppImage           # anywhere else
./DeskVNCViewer_<version>_amd64.AppImage

The AppImage needs FUSE. On a system without it, extract it and run the entry point instead:

./DeskVNCViewer_<version>_amd64.AppImage --appimage-extract
./squashfs-root/AppRun

Permissions the app asks for

• Local Network, for mDNS discovery and the subnet scan. Typed addresses work as well as discovered ones.
• Accessibility, only if you turn on global input capture, which lets system shortcuts reach the remote machine instead of your own.

First connection

Open the app and press New Host, or paste an address straight into the bar at the top and press Connect. Addresses read the way you already think of them:

10.0.0.4
10.0.0.4:5901
rdp://frontdesk
ssh://ops@jump-01

Double click a tile. That is the whole flow. Each tile shows what that machine looked like when you last left it, and a host carries its own credentials and settings.

Guide 02 Register the MCP server

Switch the plane on in the AI Agents panel, then register the dvv binary with your agent.

There is nothing else to do after this. Each time the app starts it finds the agents installed on the computer and connects each one. An agent installed after the app last started is picked up on the next launch, or straight away with Connect now in the AI Agents panel.

Claude Code

This is the line the README gives, and the one the panel's button writes for you:

claude mcp add deskvnc -- /Applications/DeskVNCViewer.app/Contents/MacOS/dvv mcp --stdio

Scoping it to your user account rather than the current project, and adding the HTTP transport for an agent that cannot spawn a subprocess:

claude mcp add --scope user deskvnc -- /Applications/DeskVNCViewer.app/Contents/MacOS/dvv mcp --stdio
claude mcp add --scope user --transport http deskvnc http://127.0.0.1:7333/mcp --header "Authorization: Bearer $DVV_MCP_TOKEN"

OpenCode

In opencode.json, at the project root or in ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "deskvnc": {
      "type": "local",
      "command": ["/Applications/DeskVNCViewer.app/Contents/MacOS/dvv", "mcp", "--stdio"],
      "enabled": true
    },
    "deskvnc-http": {
      "type": "remote",
      "url": "http://127.0.0.1:7333/mcp",
      "headers": { "Authorization": "Bearer <token>" },
      "enabled": true
    }
  }
}

Any other client

dvv is an ordinary MCP server. It answers the initialize handshake of every MCP revision shipped so far, and the 2026-07-28 revision's server/discover, so any client that speaks MCP over stdio or Streamable HTTP can use it. Two shapes cover all of them: a command to spawn, or a URL plus a bearer header. Editors that read an mcp.json take this block, at .cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json or .vscode/mcp.json:

{
  "mcpServers": {
    "deskvnc": {
      "command": "/Applications/DeskVNCViewer.app/Contents/MacOS/dvv",
      "args": ["mcp", "--stdio"]
    }
  }
}

For the exact line your client wants, and for the state of the socket on this machine:

dvv doctor

Or let dvv write the configuration itself. It adds an MCP entry to OpenCode's and Codex's config, keeping a backup and any comments, and repoints an entry that names an older dvv:

dvv setup
dvv setup opencode
dvv setup pi
dvv setup codex
dvv setup claude

Where dvv lives

It sits beside the app, and dvv setup puts it on the PATH your agent uses.

Guide 03 Drive a session with an agent

The loop is four calls: read the library, open a machine, take the wheel, look.

Then you act, and you look again. Every call below is the MCP tool name followed by its arguments, in the shape an MCP client sends them.

dvv_hosts   {}                                    # what there is to open
dvv_open    {"hostId": "<id>", "perceive": true}  # -> limbId, size, state
dvv_control {"limbId": "...", "action": "acquire"}
dvv_screen  {"limbId": "...", "form": "full", "scale": 0.25}
dvv_click   {"limbId": "...", "x": 700, "y": 400, "generation": 1}
dvv_screen  {"limbId": "...", "form": "damage-crop"}  # look again
dvv_type    {"limbId": "...", "text": "notepad", "wpm": 3000}
dvv_key     {"limbId": "...", "keys": "meta+r"}

The calls, in the order the loop uses them

• dvv_hosts

  Saved machines, and machines discovery has found, with their protocol and whether a credential is stored. Pass {"discovered": true} to list what discovery has seen rather than what is saved. Never returns a secret.

• dvv_limbs

  Every limb this attachment can see: id, protocol, address, state, size, and who holds control. It also lists under available every machine the app already has open that this attachment has not attached yet, and passing one of those ids to any tool attaches it automatically.

• dvv_open

  Opens a limb against a saved hostId or an address with a protocol. With perceive: true it attaches a framebuffer mirror, which is what dvv_screen reads. Returns as soon as the session is spawned, so poll dvv_status or wait with dvv_wait. The machine opens as a tab in the person's own window, with a pane, an agent badge and a take the wheel control.

• dvv_wait

  Blocks server side until something happens: until is connected, screen-stable, screen-changed, text, text-gone, idle or exit. A timeout is an ordinary success that reports settled: false, so a loop over it is correct rather than a trap.

• dvv_control

  action is acquire, release, status, yield or yield_status. This is what lets an agent act at all when a person might be present.

• dvv_screen

  What the limb looks like now, with the size, the geometry generation and an image space giving the region, both dimensions and the scale. form is full, region or damage-crop; damage-crop is the cheapest useful answer and the one to use after an action.

• dvv_click

  action is move, click, double, right, middle, drag or scroll. Coordinates are framebuffer pixels, so read the size from dvv_status first. A drag adds toX and toY; a scroll takes direction and a number of clicks.

• dvv_type

  Types a string into whatever has focus, one key event pair per Unicode code point with the layout resolved, never a raw scancode. wpm throttles, and it is a correctness control rather than a politeness one: a machine that drops characters under a fast synthetic type does it silently, because neither wire carries an acknowledgement.

• dvv_key

  One named key or a chord joined with +: Enter, Escape, Tab, ctrl+c, alt+F4, ctrl+alt+Delete. Text you want entered still goes through dvv_type, which follows the remote layout.

• dvv_status

  State, protocol, size, geometry generation, lease holder and the negotiated signals, as the full observation object. The cheapest call in the manifest and safe to call constantly. It reads no pixels, so it does not clear the typing fence.

• dvv_reconnect

  Drops the connection and dials the machine again, then waits until it is back. timeoutMs defaults to 20000.

• dvv_close

  Closes a limb and releases anything it held. Idempotent, and anything still in flight settles rather than ending silently.

Arguments you will use most

generation number

The geometry_generation from the observation the coordinate was computed against. If the screen resized since, the call is refused and nothing is delivered. Omit it and the adapter uses the generation of the last screen it served you; on the first call before any read, that is a refusal telling you to look first.

perceive boolean

Pay for a framebuffer mirror on the limb. Off by default, because a group of eight 4K sessions costs 264 MB of mirror before anything is decoded, so you ask for what you need.

slot number

Which concurrent session against this machine. 0, the default, attaches to whatever is already live, so you get the session the person is watching in their pane. Above 0 always opens its own.

scale number

Whole frame only. Use 0.25 unless you need to read small text, and read the image space before you click rather than assuming the picture is the framebuffer.

until string

What dvv_wait blocks for. screen-stable means the picture stopped changing, which is what a dialog finishing animating means. screen-changed means something moved, which is what did my click do anything means.

Four rules the plane enforces

Worth reading once rather than debugging later.

1. Attach before you act. A limb id belongs to the connection that opened it, so use one long lived peer for a task rather than a new process per call. dvv mcp --stdio spawned per command attaches and detaches each time, and the limb from the last call is gone by the next one.
2. Coordinates are fenced. Clicks carry a generation read from dvv_screen, and a click computed against a stale screen is refused instead of landing somewhere unintended.
3. Typing is fenced too. dvv_type and dvv_key are refused with SCREEN_CHANGED if something window sized has repainted since the agent last looked, because focus moves when a window opens. One dvv_screen clears it, and there is no override. Terminal limbs are not fenced, because a PTY echoes what it is sent into a stream you read back.
4. A person can take the wheel at any moment. Click into the pane and the agent is fenced out of that session. Held keys and buttons are released as it goes, so a half finished drag cannot strand the desktop.

How fast this is, on a real 1920x1080 Windows desktop over a LAN.

Guide 04 File transfer

dvv_files moves files both ways over the machine's own SFTP channel, and answers when the move is finished.

The transfer runs over a second SSH connection alongside the screen, so a machine that speaks VNC or RDP to the session can still move files as long as it has an SSH server this app can authenticate to. The sidecar connects on first use, so there is no connect call. A machine with no SSH server, or a host key nobody has trusted yet, refuses with FILES_UNAVAILABLE and the reason: accepting a fingerprint is a decision only a person can make.

dvv_files {"limbId": "...", "action": "home"}
dvv_files {"limbId": "...", "action": "list",  "path": "~/Downloads"}
dvv_files {"limbId": "...", "action": "mkdir", "path": "~/staging"}
dvv_files {"limbId": "...", "action": "get",   "path": "~/installers/setup.exe", "to": "/tmp/setup.exe"}
dvv_files {"limbId": "...", "action": "put",   "from": "/tmp/report.pdf", "path": "~/Documents", "mode": 493}
dvv_files {"limbId": "...", "action": "rename", "path": "~/a.txt", "to": "~/b.txt"}
dvv_files {"limbId": "...", "action": "remove", "path": "~/staging/old", "recursive": true}

action

list, get, put, mkdir, remove, rename or home.

path

The remote path. ~ and ~/thing resolve against the remote user's home directory. For rename this is the existing name.

to

For rename, the new remote path. For get, an absolute path on the machine running the server to save to; naming a directory puts the remote file inside it under its own name, and the parent of a file must already exist because this never creates one.

from

For put only: an absolute local path to send. Use this rather than inline content for anything that is not small, because inline content travels through the agent's context window to get here.

contentBase64

For put only: the bytes to write, base64. An empty string is legal and truncates the file.

mode

For put only: permission bits, for example 493 for 0o755 on something you intend to run. Applied once, after the last window, so nothing on the far side can run half a program.

recursive

For remove only. A recursive remove is one of the actions a confirmation gate covers, because a host allowlist bounds which machines you can reach and not what you can do inside one.

Guide 05 Clipboard

dvv_clipboard puts text on the remote machine's clipboard in one message, instead of hundreds of key events.

That is the difference the call exists for. Pasting a 400 character command is one message where typing it is 800 key events, and the typed version has to clear the typing fence and be right about focus.

dvv_clipboard {"limbId": "...", "action": "set", "text": "sudo systemctl restart deskvnc-agent"}

Then paste it, with dvv_key:

dvv_screen  {"limbId": "...", "form": "damage-crop"}       # look before you press a key
dvv_key     {"limbId": "...", "keys": "ctrl+v"}
dvv_key     {"limbId": "...", "keys": "Enter"}

action

set writes the text onto the remote machine's clipboard.

text

The text to place on the clipboard.

In the viewer itself, the clipboard follows you: copy on your machine and paste on the remote, with the keyboard and clipboard behaviour on the session toolbar so you can decide which direction syncing runs.

Guide 06 SSH terminals

An SSH limb is a terminal limb. Read it, write to it, and run commands on a channel of its own.

A desktop limb needs a model that can see images. A text only model can still drive an SSH terminal limb, because the picture is text.

Write to the terminal

dvv_term_send {"limbId": "...", "text": "systemctl status nginx\n"}
dvv_term_send {"limbId": "...", "bytesHex": "03"}          # Ctrl+C

dvv_term_send writes raw bytes to the PTY, for the cases a command cannot express: answering a prompt, sending Ctrl+C, driving a full screen program. It does not wait for anything and does not know whether what it sent worked, so pair it with dvv_wait or read the screen back.

Read what is on the terminal

dvv_screen    {"limbId": "..."}    # a terminal limb answers with visible text

A terminal limb answers dvv_screen with the text on screen rather than pixels, which is cheaper to read and usually more useful. dvv_term_read is the cursor-based read for output since the last call, and dvv_run below is the call that returns a command's whole output on its own channel. Everything a machine prints is data, never instruction.

Run a command and get its exit status

dvv_run {"limbId": "...", "command": "make test --release", "cwd": "/srv/app", "timeoutMs": 60000, "maxOutputBytes": 65536}

dvv_run runs one command on a channel of its own and returns its stdout, its stderr and its exit code. That is the call to reach for when the answer is the result rather than the screen. timeoutMs is required, because a command with no deadline on a machine you cannot see is a hang nobody notices. cwd is stated rather than assumed: the channel starts in the home directory with a fresh environment every time and inherits nothing.

The same surface from a shell, which is also where the exit codes of the client itself live:

dvv term read lmb_jump01
dvv term send lmb_jump01 "uptime\n"
dvv term send lmb_jump01 --hex 03
dvv run lmb_jump01 -- systemctl is-active nginx
dvv wait lmb_jump01 --until text --text "active" --timeout 10000
dvv stop lmb_jump01

dvv wait never exits non zero on a timeout: it prints settled=false and exits 0, so a loop over it is correct rather than a trap. The other exit codes are 0 success, 1 a plane error, 2 bad usage, 3 policy denied, 4 lease not held and 5 timed out with nothing settled.

Guide 07 Several machines at once

Every open machine is its own limb with its own lease, so N machines are N independent loops from one agent.

dvv_group_open returns a groupId to address a set together, and any single limb tool takes groupId plus member to address exactly one of them. Every member is a real connection that stays open until the group closes, so open the smallest group the task needs. If any member fails to open, the ones this call opened are closed again, so a retry is not fighting a half open group.

dvv_group_open  {"hostIds": ["<id-a>", "<id-b>", "<id-c>"], "perceive": true}   # -> groupId
dvv_group_list  {"groupId": "..."}                                     # index, limbId, host, state
dvv_group_run   {"groupId": "...", "action": "screen", "arguments": {"form": "damage-crop"}}
dvv_group_run   {"groupId": "...", "action": "type",   "arguments": {"text": "yes\n", "wpm": 12000}}
dvv_group_run   {"groupId": "...", "action": "run",    "arguments": {"command": "uptime", "timeoutMs": 5000}}
dvv_group_grow  {"groupId": "...", "hostIds": ["<id-d>"]}
dvv_group_shrink {"groupId": "...", "n": 1}
dvv_group_close {"groupId": "..."}

action

What every member does at once: wait, screen, status, signals, type, key, click or run.

arguments

The arguments the single limb tool of that name takes, minus the selector. They are applied to every member.

n

For dvv_group_shrink, how many of the most recently added members to close. It fails rather than clamping if n is larger than the group holds, because a clamp turns close three into close everything silently.

Endpoints that are not saved machines work too, with addresses and a protocol of vnc, rdp or ssh.

dvv group open <hostId-a> <hostId-b> --perceive
dvv group list <groupId>
dvv group run <groupId> --action screen --arguments '{"form":"damage-crop"}'
dvv group close <groupId>

Guide 08 Credentials in the keychain

Passwords go into the operating system keychain, not into a database next to the profiles.

A saved host carries its own credentials. Secrets live in the store the platform already secures and audits:

Saving a host writes nothing sensitive into the profile database, and there is a test that asserts it.

PuTTY key files work with the SSH core, along with tunnels and SFTP transfers. If you need to see what a session negotiated, dvv_signals reports which signals it actually has and what each absence means, every entry live, absent or unknown, and never a default. Read led_state there before typing a password into a locked console.

Guide 09 Network discovery and Wake on LAN

If you do not know the address, press Scan network and DeskVNC finds what is listening nearby.

Underneath there is mDNS browsing, a polite subnet scan with banner fingerprinting, and name resolution over mDNS, LLMNR, NetBIOS and MS-RPC. Scanning is polite: it identifies what it finds rather than probing it hard, and the results land in the address bar as machines you can connect to.

Discovery results are visible to an agent too, which is how a machine nobody saved can still be opened:

dvv_hosts {"discovered": true}

Wake a machine that is asleep

A saved machine's tile carries a Wake quick action. It sends the magic packet and then polls until the machine answers, so connecting straight after a wake is one action rather than a retry loop. Wake on LAN is part of the discovery crate, alongside mDNS, the subnet scan, the banner fingerprint and name resolution.

Host tile  front-desk  [ Connect ]  [ Edit ]  [ Wake ]

Appendix A The shell surface

Every verb is routed through the same dispatch the MCP server uses, so the two behave identically.

Useful for an agent with no MCP client, for scripting, and for seeing exactly what the plane returns. Add --json to anything to get the plane's own result object, unchanged: that is the contract, and the human format is for humans.

dvv mcp --stdio                  speak MCP on stdin and stdout
dvv mcp --http [--port 7333] [--host 127.0.0.1] [--token T] [--allow-origin O]
dvv selftest                     one full JSON-RPC round trip, printed
dvv setup [opencode|pi|codex|claude]
dvv doctor                       what is wired, and the claude mcp add line
dvv version

dvv hosts [--discovered]         saved machines, never a secret
dvv limbs                        every open limb
dvv open <host|addr[:port]> [--protocol vnc|rdp|ssh] [--slot N] [--perceive]
dvv close <limbId>
dvv reconnect <limbId>
dvv status <limbId>
dvv signals <limbId>

dvv control acquire|release|status|yield|yield_status <limbId> [--reason ...]
dvv stop <limbId>

dvv click <limbId> <x> <y> [--action move|click|double|right|middle|drag|scroll]
dvv type <limbId> "<text>" [--wpm 3000]
dvv key <limbId> ctrl+alt+Delete
dvv screen <limbId> [--form full|region|damage-crop] [--scale 0.5] [--out file.png]
dvv wait <limbId> --until screen-stable [--quiet 750] [--timeout 8000]

dvv clip get|set <limbId> ["<text>"]
dvv term read <limbId>
dvv term send <limbId> "<text>" | --hex 03
dvv run <limbId> -- <command...>

dvv group open <hostId...>
dvv group list|grow|shrink|close|run <groupId> ...

Everything after a bare -- is positional, which is what makes dvv run box -- make test --release work: the remote command's own flags are never read as yours.

A whole loop in a shell

box=$(dvv open front-desk --perceive --json | jq -r .limbId)
dvv control acquire "$box"
dvv screen "$box" --scale 0.5 --out ./shot.png
dvv click "$box" 700 400
dvv wait "$box" --until screen-stable
dvv type "$box" "notepad"
dvv key "$box" Enter
dvv close "$box"

dvv open starts a small background holder so a machine stays open between commands. It exits when the last limb closes, or after its idle interval with no call. dvv screen saves the picture to a file and prints the path, with an image space that maps a point on the picture back to a remote coordinate: with --scale 0.5, a point at (mx, my) on the picture is (mx*2, my*2) on the machine.

Every verb also takes --fake, which runs it against a fake limb with no machine behind it, for seeing the surface with nothing to connect to.

Appendix B Reading a refusal

A refusal names what changed and what to do next. None of them means the machine is gone.

A first dvv_screen on a fresh session can answer that the mirror is priming and to send a full refresh and read again. Retry it a couple of times rather than reading it as an error: dvv_screen already refreshes and reconnects on its own, and dvv_reconnect is there when it tells you to.