README
¶
pmux — Pocketmux Agent
pmux is a transparent drop-in replacement for tmux that makes your terminal sessions accessible from your phone. Replace tmux with pmux in your workflow — every command works identically, but sessions are automatically accessible from the Pocketmux mobile app over an encrypted peer-to-peer connection.
pmux new-session -s work # just like tmux, but now accessible from your phone
pmux attach -t work
pmux ls
Highlights
- Drop-in tmux replacement — all tmux commands pass through unchanged via a dedicated socket (
-L pmux) - Peer-to-peer encrypted — terminal data flows directly between host and phone over WebRTC DataChannels; the signaling server never sees your content
- Zero-knowledge architecture — the server only relays connection metadata, never terminal data or session information
- Ed25519 identity — no passwords, no accounts; cryptographic keypair generated locally at setup
- QR code pairing — scan once from the mobile app to establish a secure link
- OS service integration — runs as a launchd (macOS) or systemd (Linux) service with automatic restart
- Cross-platform — macOS (universal binary) and Linux (amd64, arm64)
Install
# Homebrew
brew install shiftinbits/tap/pmux
Pre-built binaries and DEB/RPM/Snap packages are available on GitHub Releases.
Getting Started
pmux init # generate identity, install service
pmux pair # scan the QR code with the Pocketmux app
pmux # start a session — it's now on your phone
Documentation
Full documentation is available at docs.pmux.io:
- Installation — platform-specific setup instructions
- Initialization — first-time setup walkthrough
- Pairing — connecting your mobile device
- CLI Reference — all commands and options
- Configuration — config file, environment variables
- Architecture — how it all works under the hood
License
MIT — see LICENSE
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
pmux
command
|
|
|
internal
|
|
|
agent
Package agent implements the core Pocketmux agent lifecycle: start, connect, shutdown.
|
Package agent implements the core Pocketmux agent lifecycle: start, connect, shutdown. |
|
auth
Package auth handles Ed25519 keypair generation, storage, and challenge signing.
|
Package auth handles Ed25519 keypair generation, storage, and challenge signing. |
|
config
Package config handles configuration file parsing, defaults, and path resolution.
|
Package config handles configuration file parsing, defaults, and path resolution. |
|
protocol
Package protocol defines wire protocol message types matching @pocketmux/shared.
|
Package protocol defines wire protocol message types matching @pocketmux/shared. |
|
proxy
Package proxy handles tmux passthrough: exec tmux -L pmux [args...].
|
Package proxy handles tmux passthrough: exec tmux -L pmux [args...]. |
|
service
Package service manages the pmux agent as an OS service (launchd on macOS, systemd on Linux).
|
Package service manages the pmux agent as an OS service (launchd on macOS, systemd on Linux). |
|
tmux
Package tmux wraps the tmux CLI for session/window/pane management.
|
Package tmux wraps the tmux CLI for session/window/pane management. |
|
update
Package update implements version checking and self-update functionality.
|
Package update implements version checking and self-update functionality. |
|
webrtc
Package webrtc manages Pion RTCPeerConnection, DataChannel, and signaling.
|
Package webrtc manages Pion RTCPeerConnection, DataChannel, and signaling. |
Click to show internal directories.
Click to hide internal directories.