Configuration

pmux stores its configuration at ~/.config/pmux/config.toml. The file is created by pmux init with sensible defaults. Most users will never need to edit it.

Config precedence

Configuration values are resolved in three layers, where each layer overrides the previous:

1. Defaults -- built into the pmux binary.
2. Config file -- values set in ~/.config/pmux/config.toml.
3. Environment variables -- override both defaults and file values.

Run pmux config to see the effective values with source annotations showing where each value came from (default, file, or env).

Schema reference

TOML key	Type	Default	Env override	Description
name	string	OS hostname	--	Display name shown on the paired mobile device
log_level	string	info	PMUX_LOG_LEVEL	Agent log verbosity
server.url	string	https://signal.pmux.io	PMUX_SERVER_URL	Signaling server base URL
identity.key_path	string	~/.config/pmux/keys/	PMUX_KEY_PATH	Directory containing the Ed25519 public key
identity.secret_backend	string	auto	PMUX_SECRET_BACKEND	Secret storage backend
connection.reconnect_interval	duration	5s	--	Delay between signaling reconnect attempts
connection.keepalive_interval	duration	30s	--	WebSocket heartbeat interval
connection.max_mobile_connections	integer	1	PMUX_MAX_CONNECTIONS	Maximum concurrent mobile connections
tmux.socket_name	string	pmux	PMUX_SOCKET_NAME	tmux socket name for the -L flag
tmux.tmux_path	string	(empty)	PMUX_TMUX_PATH	Absolute path to the tmux binary

Top-level

name -- the host display name shown on the paired mobile device. Set during pmux init using the OS hostname. Edit the value directly in config.toml to change it. If unset, the agent resolves the OS hostname at runtime.

log_level -- controls the agent's log verbosity. Accepted values are debug, info, warn, and error. The default is info. Useful for troubleshooting: set to debug for verbose output, or error to suppress routine messages. Logs are written to ~/.config/pmux/agent.log.

[server]

url -- the signaling server base URL. Accepts http://, https://, ws://, or wss:// schemes. The agent converts HTTP URLs to WebSocket URLs internally when connecting. Validation rejects any URL that does not start with one of these four schemes.

The legacy environment variable PMUX_AGENT_SIGNAL_URL is also supported, but PMUX_SERVER_URL takes precedence when both are set.

[identity]

key_path -- the directory where ed25519.pub (the Ed25519 public key) is stored. The private key is not stored as a file in this directory. It lives in the secret backend instead.

secret_backend -- controls where private keys and shared secrets are stored. Three values are accepted:

• auto (default) -- tries the system keychain first. Falls back to an encrypted file if the keychain is unavailable.
• keyring -- uses macOS Keychain or Linux SecretService via D-Bus. Fails with an error if neither is available.
• file -- uses NaCl SecretBox (XSalsa20-Poly1305) encryption. Stores secrets at <key_path>/secrets.enc.

Validation rejects any value other than auto, keyring, or file.

[connection]

reconnect_interval -- a Go duration string (e.g., 5s, 1m30s, 500ms). Controls the delay between reconnect attempts when the signaling server connection drops. Must be a valid Go duration or validation fails.

keepalive_interval -- a Go duration string. Controls the WebSocket heartbeat interval used to maintain the signaling connection. Must be a valid Go duration or validation fails.

max_mobile_connections -- the maximum number of concurrent mobile connections. Must be 1 in the current release, which enforces the single-pairing model. Validation rejects any other value.

[tmux]

socket_name -- the tmux socket name passed to -L. All pmux commands use this socket. Changing it creates a completely separate tmux namespace. The default value pmux keeps Pocketmux sessions isolated from regular tmux sessions. Must not be empty.

tmux_path -- the absolute path to the tmux binary. pmux init discovers and saves this automatically using $PATH lookup. This ensures the agent can find tmux even when launched by a service manager (launchd/systemd) where $PATH may be minimal. If empty, the agent falls back to searching $PATH at runtime. Set this manually if tmux moves to a different location after initialization.

Annotated example

A complete config.toml with all fields set:

# Host display name (shown on paired mobile device)
name = "my-workstation"
# Log level: "debug", "info", "warn", or "error" (env: PMUX_LOG_LEVEL)
log_level = "info"

[server]
# Signaling server URL (env: PMUX_SERVER_URL)
url = "https://signal.pmux.io"

[identity]
# Ed25519 key directory (env: PMUX_KEY_PATH)
key_path = "~/.config/pmux/keys/"
# Secret storage: "auto", "keyring", or "file" (env: PMUX_SECRET_BACKEND)
secret_backend = "auto"

[connection]
# Reconnect delay after signaling disconnection
reconnect_interval = "5s"
# WebSocket heartbeat interval
keepalive_interval = "30s"
# Maximum mobile connections (must be 1)
max_mobile_connections = 1

[tmux]
# tmux socket name for -L flag (env: PMUX_SOCKET_NAME)
socket_name = "pmux"
# Absolute path to tmux binary (env: PMUX_TMUX_PATH)
# Resolved automatically during 'pmux init'. Set manually if tmux moves.
tmux_path = "/opt/homebrew/bin/tmux"

When pmux init creates the file, all values are commented out so they act as documentation without overriding the built-in defaults.

Environment variables

Variable	Config equivalent	Notes
PMUX_SERVER_URL	server.url	Takes precedence over both the config file and PMUX_AGENT_SIGNAL_URL
PMUX_AGENT_SIGNAL_URL	server.url	Legacy. Lower precedence than PMUX_SERVER_URL
PMUX_LOG_LEVEL	log_level	Must be debug, info, warn, or error
PMUX_KEY_PATH	identity.key_path	Overrides the key directory path
PMUX_SECRET_BACKEND	identity.secret_backend	Must be auto, keyring, or file
PMUX_MAX_CONNECTIONS	connection.max_mobile_connections	Parsed as an integer. Must be 1
PMUX_SOCKET_NAME	tmux.socket_name	Overrides the tmux socket name
PMUX_TMUX_PATH	tmux.tmux_path	Overrides the tmux binary path

File paths

All files and directories pmux creates:

Path	Created by	Purpose
~/.config/pmux/	pmux init	Configuration root directory
~/.config/pmux/config.toml	pmux init	Configuration file
~/.config/pmux/keys/	pmux init	Key storage directory
~/.config/pmux/keys/ed25519.pub	pmux init	Ed25519 public key
~/.config/pmux/keys/secrets.enc	pmux init	Encrypted secrets (file backend only)
~/.config/pmux/paired_devices.json	pmux pair	Paired mobile device information
~/.config/pmux/agent.pid	Agent startup	Background agent PID file
~/.config/pmux/agent.log	Agent startup	Agent debug log
~/Library/LaunchAgents/io.pmux.agent.plist	pmux agent install	launchd service (macOS only)
~/.config/systemd/user/pmux.service	pmux agent install	systemd user service (Linux only)