Install & run Portty

Quick start

Portty ships two binaries:

• portty — wrap and share a terminal (the relay).
• portty-host — the paired-device daemon.

Install on the machine you want to reach (macOS, Linux, Windows, or a Raspberry Pi). The phone is always the viewer — it never runs a shell.

# macOS
brew install mrtechnoo/tap/portty

# Linux
curl -fsSL https://raw.githubusercontent.com/mrtechnoo/portty/main/install.sh | sh

# Windows
winget install CorvuxMindware.Portty

# Windows, with Scoop
scoop bucket add portty https://github.com/mrtechnoo/portty
scoop install portty

Prefer a plain download? Every platform's archive, with a SHA256SUMS file to verify it, is on the latest release. Portty is open source under Apache-2.0 — the source code is on GitHub.

Then start the host and pair:

portty-host    # start the host (pairing stays closed)
portty pair    # show a QR, then confirm the 6-digit code

Pair your phone

1. Run portty pair on your machine (start portty-host first if it isn't running). Leave it open.
2. Open Portty on your phone (Android: get it on Google Play; iPhone coming soon), tap Connect to a host and scan the QR (or paste the ticket).
3. Both screens show the same 6-digit code. If they match, answer y in the portty pair terminal. There's no PIN to type.
4. You're connected over encrypted P2P — LAN direct, NAT-punched, or relayed. No ports, no VPN.

Share any terminal

portty share opens a portal from the terminal you're already sitting in:

portty share          # the current terminal is now on your phone

To make every new terminal portal-ready from birth:

portty install        # adds a profile hook (PowerShell $PROFILE / .bashrc)

Run as a service

Run the host in the background so it survives logout/reboot and restarts on crash.

macOS (launchd, per-user)

cp packaging/launchd/com.corvuxmindware.portty.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.corvuxmindware.portty.plist

# host log (it never contains pairing keys; pair with `portty pair`):
tail -f ~/Library/Logs/portty-host.log

Linux (systemd, per-user)

mkdir -p ~/.config/systemd/user
cp packaging/systemd/portty-host.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now portty-host
journalctl --user -u portty-host -f

Windows

No bundled service yet. Run portty-host serve in a background terminal, or wrap it with NSSM:

nssm install portty-host "C:\Program Files\Portty\portty-host.exe" serve

Manage peers

portty-host status      # is the daemon running? (pid)
portty-host peers       # list paired devices
portty-host revoke <id> # drop a device within ~2s

Upgrades

Replace the portty-host binary and restart the service (launchctl unload/load, systemctl --user restart portty-host, or portty-host stop and let the supervisor relaunch). Device identity and paired-peer state persist across upgrades in the per-user data dir.

Troubleshooting

• Closed laptop is unreachable. That's physics — Portty needs an always-on machine. Target a server, desktop, or Pi as the host.
• Pairing a phone when the host runs as a service. Run portty pair in a terminal as the same user — it talks to the running service and shows the QR and code there. Nothing secret is written to service logs.
• Corporate EDR blocks it. An outbound tunnel + remote shell looks like a reverse shell. Use signed binaries and the auditable self-host mode; talk to your security team.
• Phone can't connect after an upgrade. The computer and the phone app must speak the same protocol version — update both. If it still can't connect, pair again with portty pair.
• Still stuck? Email support@meetcorvux.com or open an issue on GitHub.