GitHub - zkalykov/couchpilot: Run your Mac from the couch: terminal + full screen control in your phone's browser. LAN-only, no cloud. · GitHub
/" data-turbo-transient="true" />
Skip to content
Search or jump to...
Search code, repositories, users, issues, pull requests...
-->
Search
Clear
Search syntax tips
Provide feedback
--><br>We read every piece of feedback, and take your input very seriously.
Include my email address so I can be contacted
Cancel
Submit feedback
Saved searches
Use saved searches to filter your results more quickly
-->
Name
Query
To see all available qualifiers, see our documentation.
Cancel
Create saved search
Sign in
/;ref_cta:Sign up;ref_loc:header logged out"}"<br>Sign up
Appearance settings
Resetting focus
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
zkalykov
couchpilot
Public
Notifications<br>You must be signed in to change notification settings
Fork
Star
main
BranchesTags
Go to file
CodeOpen more actions menu
Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit
History<br>1 Commit<br>1 Commit
src/couchpilot
src/couchpilot
tests
tests
.gitignore
.gitignore
LICENSE
LICENSE
README.md
README.md
pyproject.toml
pyproject.toml
View all files
Repository files navigation
couchpilot
Run your Mac from the couch. A real terminal and your full screen, with mouse<br>and keyboard, in your phone's web browser. Everything stays on your home<br>network: no cloud, no relay, no accounts, nothing leaves your LAN.
$ couchpilot
couchpilot v0.1.0 ● serving<br>──────────────────────────────────────────────────────────<br>connect a device<br>█████████████████ scan with the phone's camera, or open:<br>██ ▄▄▄▄▄ █▀ █▀▀██ https://your-mac.local:8443/?p=S8KQWW<br>██ █ █ █▀ ▄ ▀██<br>██ █▄▄▄█ █ ▀▄▀▄██<br>██▄▄▄▄▄▄▄█▄█▄███<br>█████████████████ use Wi-Fi you trust - this link is the key to your Mac<br>──────────────────────────────────────────────────────────<br>s stop · h hide QR · w keep-awake on · r rotate · q quit
Scan the QR. Your phone shows up on the Mac as a numbered device; press that<br>number to let it in. That's the whole setup.
Install
macOS and Python 3.11+. Not on PyPI yet, so install straight from GitHub:
uv tool install git+https://github.com/zkalykov/couchpilot<br># or<br>pipx install git+https://github.com/zkalykov/couchpilot
Then run couchpilot. To try it without installing anything:
uvx --from git+https://github.com/zkalykov/couchpilot couchpilot
What you get on the phone
terminal — a real shell (xterm.js) with arrows, ctrl, paste, and the<br>on-screen keyboard.
screen — live view of the Mac with three modes along the bottom:
touchpad — drag to move the cursor, tap to click, two-finger tap for<br>right-click, two-finger drag to scroll, pinch to zoom, three-finger swipe<br>to switch desktops. Buttons for zoom, panning, "left hold" (drag things)<br>and right click. With two or more monitors a display switch appears.
commands — ⌘ ⌃ ⌥ ⇧ modifiers plus esc, tab, return, delete, arrows.
type — opens the phone keyboard and types straight into the Mac,<br>zoomed in on the cursor so you can read what you're doing.
Keeping it secure
The threat model is simple: anyone with the link controls your Mac, so the<br>link is treated like a key.
The URL carries a random 192-bit token; without it every request is refused.
Each new device must be approved by number on the Mac before it can do<br>anything. One device at a time by default.
Traffic is HTTPS/WSS, signed by a local CA created on first run. The CA is<br>name-constrained to private addresses, so even a stolen CA key can't forge<br>certificates for real websites.
r rotates the token: old links and sessions die instantly.
When the connection drops, the phone blanks the screen view immediately<br>rather than leaving the last frame visible.
Nothing runs unless the panel is open, and quitting stops everything.
Run it on Wi-Fi you trust. --open (no approval) and --multi (several<br>devices) loosen the defaults if you really want that.
The certificate warning
Your phone doesn't know couchpilot's local CA yet, so the first visit shows a<br>browser warning. Two options:
tap through it (iOS Safari then uses an encrypted fallback transport), or
install the CA once: open http://:8444/ in Safari (the port is your<br>main port + 1), install the profile, then enable it under Settings →<br>General → About → Certificate Trust Settings. After that every browser on<br>the phone connects at full speed with no warnings.
Keep the Mac awake
Press w to keep the Mac working with the lid closed (it runs<br>sudo pmset -a disablesleep 1 plus caffeinate, and asks for your password<br>in the terminal). Opening the lid locks the screen immediately. On battery you<br>pick a time budget first, in 30-minute steps, so a Mac in a bag can't cook<br>itself. Normal sleep is always restored on...