Hướng dẫn sử dụng SwiftDeskSwiftDesk user guide

1. Install the host on Windows

Since 0.7.0 the Windows build is one app: it hosts this computer and also controls other ones (see section 3). Install it in the Windows account you normally sign in with.

Option 1: installer

1. Download SwiftDesk-Host-Setup-Windows.exe, run it and click Install.
2. Windows Defender Firewall asks once: click Allow access so other devices on your network can connect.
3. The SwiftDesk icon appears in the system tray. Windows 11 often hides new icons under the ^ arrow: drag it onto the taskbar to keep it visible. Right-click it for the Address and PIN, left-click to open the SwiftDesk window.

Option 2: one PowerShell line

irm https://swiftdesk.platformforge.dev/install.ps1 | iex

It downloads the latest installer and installs it for the current user. To read it first, open install.ps1 in a browser.

Windows session notes

• The host captures the signed-in session. While the machine is locked, at the sign-in screen or a UAC prompt, nothing can be captured; the host reconnects when the desktop is back.
• Laptop lid closed: still works. With the built-in display off, the host falls back to GDI capture; motion may be less smooth than the GPU path.
• Through Remote Desktop (RDP): the host shares the RDP session's virtual display. If you disconnect RDP, Windows drops that display and clients see black until you sign back in.
• Settings and the PIN live in %APPDATA%\swiftdesk\host.json; the log is %LOCALAPPDATA%\swiftdesk\host.log.

2. Install the host on macOS

SwiftDesk-macOS.pkg installs the SwiftDesk app and the SwiftDesk Host app. The host is a universal build for Intel and Apple silicon, macOS 12 or later.

1. Open the .pkg and install. If macOS cannot verify the developer: System Settings → Privacy & Security → Open Anyway.
2. Open SwiftDesk Host. macOS asks for Screen Recording: in System Settings → Privacy & Security → Screen & System Audio Recording, enable SwiftDesk Host.
3. On the first mouse or key event from a client, macOS asks for Accessibility: enable SwiftDesk Host under Privacy & Security → Accessibility.
4. Restart the host (Quit from the menu bar, then open it again) so the permissions apply.

After an update, macOS may treat the host as a new app and ask again. Open the same two panes, remove the old SwiftDesk Host entry with “−”, add it again with “+”, then restart the host. For the .pkg install the log is /tmp/swiftdesk-host.log.

3. Connecting

From the desktop app (Windows, macOS)

Windows and macOS share one app. Left-click the tray icon to open the SwiftDesk window: Your address and this computer's PIN sit at the top, with two tabs below:

• This computer: who is connected now, paired devices, approval prompts, audit log.
• Connect to another computer: quick connect (address[:port] and PIN) and an address book with Add, Edit, Delete, Import. Each remote computer opens in its own SwiftDesk window.

The tray menu (right-click) also has Connect to…. So a Windows PC can now control other computers without a browser.

From the Android app

1. Tap Scan QR and scan the code in the SwiftDesk window of the computer you want to control: the app adds and pairs it.
2. Or tap Add host, pick SwiftDesk, and enter a name and the address. The port is part of the address and optional: 192.168.1.20 or 192.168.1.20:7340. The app asks for the PIN the first time you open it.

Each entry's ⋮ menu has Edit, Duplicate, Forget pairing and Delete. Exporting and importing the address book: see section 4. iPad/iOS: coming soon.

From a browser, nothing to install

1. Open http://192.168.1.20:7340/ in Chrome, Safari, Firefox or Edge.
2. Pick a device name, type the PIN, click Connect. The token is kept in that browser.

With a QR code

On the host itself, the SwiftDesk window (left-click the tray icon) or http://127.0.0.1:7340/admin shows a QR code. On a phone, tap Scan QR in the app to add and pair; scanning with the camera opens the web client with the PIN filled in. On desktop or web, paste the QR link.

Which address?

Use IP addresses:

• Same Wi-Fi or LAN: the host's local IP, for example 192.168.1.20.
• Over Tailscale: the host's Tailscale IP (of the form 100.x.y.z). Your address in the SwiftDesk window and the tray's Address line prefer the Tailscale IP.

SSH

Add host → SSH → address (port 22 by default), user, optional password. On first connect the app shows the server key fingerprint to confirm and pins it; if the key later changes, the app warns clearly and asks you before accepting the new key. The terminal is xterm-compatible with 10 000 lines of scrollback.

4. VNC, RDP and saved passwords

VNC

The app has a built-in VNC viewer; VNC is in the app only, not in the browser. Add host → VNC → address.

• A Mac: turn on Screen Sharing in System Settings → General → Sharing, then sign in with the Mac account name and password.
• Standard VNC servers: enter the VNC server password.

RDP

An RDP entry stores a Windows PC's address and opens it with Microsoft's Remote Desktop / Windows App (that app must be installed). Built-in RDP inside SwiftDesk is still coming.

Saved passwords

Tick Remember password when you enter one: it is stored in the system keychain, not in the address book file.

Exporting and importing the address book

• Hosts only: just the host list, no passwords or tokens.
• Hosts + saved passwords (encrypted): includes saved passwords, encrypted with AES-256-GCM using a passphrase you choose. The file cannot be opened without it, so keep it safe.
• Import detects encrypted files and asks for the passphrase. When a host already exists you choose Replace, Keep both or Skip.

5. PIN, owner and admin

• Rotate (default): a new PIN after every successful pairing, so each PIN works once.
• Fixed: the PIN stays until you change it, AnyDesk style. Setting a PIN in the UI switches to Fixed.
• Owner: the first device that pairs. It gets Manage host in the app and web client: view and change the PIN and mode, change device roles, revoke devices, read the audit log. Re-pairing with the PIN always drops to the user role.
• Ask me before anyone connects: turned on at the host computer itself (tray menu or SwiftDesk window). When a non-owner device connects, the person at the host presses Accept or Decline in the SwiftDesk window; with no answer it is declined after 30 seconds. Approval is not done from the owner's app.
• Pause new connections: refuse new sessions, keep the open ones.
• Revoke from the tray, admin page, owner app or cloud: that device's live sessions end at once and it must enter the PIN again.
• Audit log: every pairing, connection, revocation, PIN change and received file goes to audit.log next to host.json.
• Brute-force protection: 5 failures from one IP lock it out for 60 seconds; 30 failures from any IP within 10 minutes lock pairing and rotate the PIN in Rotate mode.

6. Tray icon

Icon colors: blue idle, green while someone is connected, grey when paused. A notification appears whenever a device connects.

• Left-click: opens the SwiftDesk window: Your address and PIN at the top, a This computer tab (connected now, paired devices, approvals, audit log) and a Connect to another computer tab.
• Right-click (Ctrl-click on a Mac): opens the menu, which shows Address and PIN; click either to copy.

7. In a session

The app and the web client have different toolbars. Web client: the toolbar shows while the pointer is over the picture. App: the toolbar hides after 3 seconds; tap the small ▾ handle at the top to bring it back.

App toolbar

Web client toolbar

After a dropped connection the web client reconnects by itself; the app shows an error with a Retry button.

Mouse, keyboard, touch

The pointer maps 1:1 onto the remote screen; keys are sent as physical key codes, so Ctrl+C or Cmd+Space behave like a keyboard plugged into the host. Text from the on-screen keyboard is sent as text, so any language works. The two touch modes and pinch zoom are in the app:

Clipboard and files

• Text copied on the host reaches owner devices automatically. To send your device's clipboard to the host: press Send clipboard in the app, or Ctrl/Cmd+V in the web client.
• Files: drag and drop them onto the picture in the web client. They land in Downloads/SwiftDesk/, up to 4 GB per file and 16 GB per session, marked as downloaded from the internet so Windows and macOS warn on open.

8. Quality and weak networks

• Defaults: up to 60 fps, 8 Mbps ceiling, hardware encode. A static screen costs almost no bandwidth.
• The app's Quality button: Low 2 Mbps (weak 4G), Normal 8, High 20 (video). It is a ceiling; the host still lowers it when the link cannot keep up.
• Below about 3.5 Mbps the host drops to 75 % resolution, up to 45 fps; below 1.5 Mbps to 50 %, up to 30 fps. The floor is 500 kbps, where text stays readable.
• The client shows “Network limited: … kbps, 75 % resolution, 45 fps”. When the link recovers the host steps back up, about one step every 5 seconds.
• Opus audio carries FEC, so it keeps playing through packet loss. If the picture stays broken, press Sharpen.
• Smoothest on 5 GHz Wi-Fi or Ethernet, and a direct Tailscale path (tailscale status does not say “relay”).

9. Remote access and network scope

SwiftDesk is LAN and Tailscale first. The host only accepts peers inside the chosen scope; others are refused before the PIN check:

To reach your home computer while away: install Tailscale on both devices with the same account and use the host's Tailscale address. Do not expose port 7340 to the internet.

SwiftDesk Cloud (optional): passkey sign-in, all your hosts in one list, change PINs and revoke devices remotely, invite family members, and relay the handshake when the two machines cannot see each other. Media stays end-to-end encrypted between the two machines.

10. AI Terminal

AI Terminal gives you persistent terminals hosted by SwiftDesk on the host. It lists and resumes Claude Code, Codex and Cursor sessions grouped by project, and starts new ones: New shell, Claude, Codex or Cursor.

Opening AI Terminal

• Browser: http://192.168.1.20:7340/term.
• App: the host's menu → AI terminals.

Owner devices only

A terminal is full access to the machine, so only owner devices can use it. To make your device an owner: on the host, open the SwiftDesk window → Paired devices → Make owner.

How long sessions live

Closing the browser or app, or losing the network, does not end a session.

AI Terminal does not go through the SwiftDesk Cloud relay yet: connect directly over your LAN or Tailscale. Linux host (terminal only, no screen sharing): coming as a download.

11. Command line

The host is a single binary, swiftdesk-host. Common flags:

12. Troubleshooting

13. Updating

• Windows: run the new installer or the PowerShell line.
• macOS: install the new .pkg; if macOS asks again, re-grant the permissions as in section 2.
• Android: install the new APK over the old one.
• The web client ships inside the host: update the host and the web client updates too.