Get started with setup-ssh

I made setup-ssh because I kept repeating the same SSH setup between my own computers. Add your devices once, sync them, and use names like ssh mac instead of remembering addresses.

The source and longer documentation live in BeepBoopBit/setup-ssh on GitHub.

Before you start

You need Python 3.11 or newer on the computer running setup, and OpenSSH enabled on each computer you want to connect. Linux, macOS, and Windows are supported. The devices must be able to reach one another over a LAN or a private network you have already configured. I use NetBird; setup-ssh does not install it.

Enroll accounts you want to grant mutual SSH access. Every enrolled account can connect to the others after a complete sync. Each device keeps its own dedicated private key; setup exchanges public keys. The repository’s access model explains the details.

Install uv

If you already have uv, skip to the next section. Otherwise, follow the uv installation guide. On Linux or macOS:

curl -LsSf https://astral.sh/uv/install.sh | sh

On Windows, run this in PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Reopen your terminal if prompted, then check uv --version.

Install setup-ssh with uv

Install the published package from PyPI and start the setup wizard. These commands work in a terminal or PowerShell:

uv tool install setup-ssh-cli
setup-ssh init

The package is named setup-ssh-cli; the command is setup-ssh. You do not need to clone the repository. This installation keeps the command available for later management. Use setup-ssh --help to see all commands.

If your shell cannot find the installed command, run uv tool update-shell and reopen your terminal. The uv installer also prints PATH instructions for your shell.

You can also install with python -m pip install setup-ssh-cli inside a Python virtual environment. Choose one installation method.

Run with uvx instead

If you prefer to run the tool without a persistent command installation, use uvx:

uvx --from setup-ssh-cli setup-ssh init

--from setup-ssh-cli selects the package that provides the setup-ssh executable. Use the same prefix for later management commands:

uvx --from setup-ssh-cli setup-ssh list
uvx --from setup-ssh-cli setup-ssh sync --skip-offline

The remaining examples use the installed setup-ssh command. If you chose uvx, replace setup-ssh with uvx --from setup-ssh-cli setup-ssh in those examples. Both methods use the same saved device inventory; commands such as init and sync still configure your devices.

Add your computers

The next step is the device wizard. On the computer you want to manage the group from, run this if you have not already started it above:

setup-ssh init

Include the current computer when the wizard asks. That lets it use its own managed key for later syncs. Give each device a shortcut name, reachable address, username, operating system, and SSH port. Use the current computer’s address that the other devices can reach.

Keep all devices online for the first sync. The wizard syncs once you have added at least two devices. Verify the host fingerprints when prompted; you may need each account’s password for the initial connection. Passwords are not saved. See the host-key verification instructions for checking the fingerprints on each operating system.

If enrollment succeeds but sync fails, fix the reported problem and run setup-ssh sync. The devices are already saved; you do not need to enroll them again.

Use your shortcuts

For devices you named mac and linux, try:

# From Linux
ssh mac
scp notes.txt mac:~/

# From the Mac
ssh linux

Use the names you chose in the wizard. After setup, these are normal OpenSSH commands. The other devices do not need the setup-ssh CLI installed just to connect.

Add another device later

Enable OpenSSH on the new computer, then return to your original setup computer:

setup-ssh add --no-sync
setup-ssh sync --skip-offline

This saves the new device and updates the computers that are available. Run sync again when the others are online so they receive the new public keys too. If everyone is already online, setup-ssh add enrolls and syncs in one step.

--skip-offline skips devices whose SSH port cannot be reached. Authentication errors and host-key mismatches still fail the run. It does not arrange background retries.

Check the group

setup-ssh list
setup-ssh plan
setup-ssh check

list shows your saved devices. plan shows the intended connections. check tests every direction and requires the whole group to be online. A successful sync with --skip-offline only verifies the devices available during that run.

For operating-system setup instructions, use setup-ssh doctor --os windows, --os linux, or --os macos.

Update or remove access

Update the CLI with the same tool you used to install it:

uv tool upgrade setup-ssh-cli

To remove an enrolled device’s managed access, run this from the setup computer, replacing desktop with its name:

setup-ssh remove desktop

Keep the other computers reachable so removal can revoke the device’s key there. Sync offline peers later. Uninstalling the CLI alone does not revoke previously granted SSH access.

For file locations, backups, recovery, and more options, read the usage guide. If a connection fails, start with the troubleshooting guide.