Skip to main content

Initialization

pmux init is a one-time setup command that creates your cryptographic identity and configuration.

What init does​

Init generates an Ed25519 keypair, creates the ~/.config/pmux/ directory structure, writes a default configuration file, discovers the absolute path to your tmux binary, and installs the agent as an OS service. The private key is stored securely in your system keychain or an encrypted file, never as plaintext on disk.

Running init​

pmux init

The command prompts for a host name and then generates your identity:

Host name [my-macbook]:

Identity generated.
Device ID: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
Host name: my-macbook
Keys saved to: /Users/you/.config/pmux/keys/ (backend: keyring)

Service installed. Agent is running.

The device ID is derived from the first 16 bytes of the SHA-256 hash of your public key, encoded as 32 hex characters. This ID uniquely identifies your host during pairing and authentication.

Init also discovers the absolute path to tmux (e.g., /opt/homebrew/bin/tmux) and saves it in config.toml as tmux.tmux_path. This ensures the agent can find tmux when launched by a service manager (launchd/systemd) where $PATH may be minimal. If tmux is not found, init prints a warning -- install tmux and re-run pmux init, or set tmux.tmux_path manually in config.toml.

What gets created​

~/.config/pmux/
├── config.toml          # configuration
└── keys/
    └── ed25519.pub      # your public key (safe to share)

The private key is not stored as a plain file. It is held by the secret backend -- either your system keychain or an encrypted file at keys/secrets.enc. See the Configuration reference for details on all config options.

Host name​

Init prompts for a display name shown on your paired mobile device. Press Enter to accept the default, which is your OS hostname (or my-host if the hostname cannot be determined). You can change it later by editing the name field in config.toml.

Secret storage​

Secret backend options

The identity.secret_backend setting in config.toml controls where your private key is stored:

  • auto (default) -- uses the system keychain if available, falls back to an encrypted file
  • keyring -- requires macOS Keychain or Linux SecretService (D-Bus); fails if unavailable
  • file -- always uses a NaCl SecretBox encrypted file at keys/secrets.enc

See the Configuration reference for full details on identity.secret_backend.

Running init again​

Running pmux init when an identity already exists displays the existing device ID and host name without regenerating keys:

Identity already exists.
Device ID: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
Host name: my-macbook

Init is safe to run multiple times.

Next steps​

Continue to Pairing to connect your mobile device.