This guide shows you how to configure OpenSSH to work with Pangolin SSH on a host running Newt, including the settings needed for trusted certificates and user resolution.
Before you begin, make sure you have a Pangolin Cloud or Enterprise Edition environment ready. This guide assumes you are able to create a site, install Newt, and configure SSH on the target host.
You will need:
If you are starting from scratch, create a site in the Pangolin dashboard first. This gives you the ID, secret, and endpoint values needed to run Newt. To avoid mistakes, copy the full run command from the dashboard and save it somewhere safe for later.
Next, install Newt on the host you want to SSH into:
curl -fsSL https://static.pangolin.net/get-newt.sh | bashThen install a Pangolin client on the machine you will connect from. For Linux and macOS terminal users, install the CLI:
curl -fsSL https://static.pangolin.net/get-cli.sh | bashOn Windows, install the desktop client from the downloads page.
Both parts are required. Newt connects the server to Pangolin, and the client provides the active Pangolin connection needed for pangolin ssh.
If you already have a site, Newt, and a Pangolin client set up, continue below.
To use Pangolin SSH, create a private resource for the host in the Pangolin dashboard. Access is denied by default, so you must grant it explicitly.
Setup is simple:
127.0.0.1 or localhost, since SSH usually listens locally and Newt runs on the same machine.my-host.internal. For larger setups, something like ssh.<siteid>.internal scales better.admin role has SSH access without needing explicit definition. Access to SSH should be granted to other necessary users or roles through the access policy.Access is managed in two layers:
By default, the admin role already has SSH access. Since you will most likely be an administrator of the Pangolin instance, you should not need to grant yourself access manually. Once everything is working, assign access through roles so it is easier to manage across a team.
For a same-host setup, run Newt with auth-daemon enabled
sudo newt --id <id> --secret <secret> --endpoint <endpoint> --auth-daemonReplace <id>, <secret> and <endpoint> with the values from the site configuration in the Pangolin dashboard. If you saved the run command from the dashboard, you can simply append --auth-daemon before running it.
In this mode, Newt handles both roles on the same machine: it acts as the site connector and provides the auth-daemon required by the local SSH server.
For initial setup, running Newt in the foreground is the quickest way to confirm the SSH flow works. If you want it to run persistently, refer to the site installation docs for the supported service management options.
To confirm that the --auth-daemon flag is being used, check the first few log lines for Auth daemon starting and auth-daemon running.
The SSH server must trust the Pangolin CA and use Newt to resolve principals for the connecting user.
Add the following to /etc/ssh/sshd_config:
TrustedUserCAKeys /etc/ssh/ca.pem
AuthorizedPrincipalsCommand /usr/local/bin/newt auth-daemon principals --username %u
AuthorizedPrincipalsCommandUser rootThese settings tell sshd to trust certificates signed by the Pangolin CA and ask Newt which principals should be applied for the user connecting. This is what links OpenSSH to Pangolin’s identity and certificate flow.
By default, Newt writes the trusted CA file to /etc/ssh/ca.pem.
After updating sshd_config, restart the SSH service:
sudo systemctl restart sshBefore you can use SSH, you need an active Pangolin connection on the client machine.
If you are using the CLI as your Pangolin client, start it with:
pangolin loginpangolin upYou can also use another Pangolin client, such as the macOS app, and use the CLI only for the SSH command.
pangolin ssh handles the SSH workflow, but it still depends on an active Pangolin client connection to the private resource network. The SSH session then travels over that Pangolin path to the host, rather than through a public SSH port. In a same-host setup, Newt forwards the connection locally to the host’s SSH service.
From a machine with an active Pangolin tunnel, connect with:
pangolin ssh my-host.internalYou can also use the resource identifier instead of the alias, but the alias is easier to remember and easier to manage across a team.
If the SSH server uses a non-default port, specify it explicitly:
pangolin ssh my-host.internal -p 2222In a same-host setup, the connection goes directly to the server running Newt over the Pangolin path. It does not pass through another internal SSH hop first.
If the connection succeeds, your same-host Pangolin SSH setup is working. From there, the remaining steps are operational: deciding who should have access, whether they should have sudo, and how you want to roll this out to more hosts.
When a user runs pangolin ssh, Pangolin creates a temporary SSH key for that session, signs it if the user is allowed to access the resource, and the host validates it against the trusted CA. Pangolin then maps the user to a local account, creating or updating it just before the session starts.
This means you do not need to manually pre-stage SSH keys or user accounts for every person who connects.
The signed SSH certificate is valid for 5 minutes to start the session. It is only used for login, so once the SSH session is established, it can stay open.
This makes access more secure than relying on long-lived static SSH keys.
Pangolin lets users reach the host over a private access path, so you do not need to expose SSH publicly.
Access is tied to the Pangolin resource and the user’s identity, rather than old SSH keys that may still be trusted long after they should have been removed. Pangolin checks access before signing the key, and the host only trusts certificates from the Pangolin CA.
That gives you a cleaner way to manage who can connect, how access is granted, and how it is removed.
If your team is looking at SSH more broadly, this is a practical example of the modernization approach covered in our Modernizing Enterprise SSH article.
If the setup does not work the first time, the cause is usually something simple.
The private resource exists, but SSH still fails
Check that the resource points to the correct host and that the user or role has been granted access. Pangolin only signs SSH certificates for resources the user is allowed to reach.
The SSH port is not allowed
If SSH uses a non-default port, make sure that port is allowed in the resource’s port restrictions. If it is blocked there, the connection will fail.
Newt is not running with --auth-daemon
For a same-host setup, Newt must be started with --auth-daemon. If that flag is missing, the SSH flow will not work correctly.
SSH refuses the connection
You can check the SSH logs with journalctl -u ssh. Add -f to follow the logs in real time while you retry the login.
The most common issues are:
SSH warns about binary permissions
Because the principals command runs as root, the Newt binary should also be owned by root. If it is owned by another user, SSH may show a warning or return an error.
To fix it, run:
sudo chown root:root $(which newt)The Pangolin client is not connected
pangolin ssh still requires an active Pangolin client connection. If pangolin up is not running, or the desktop client is disconnected, SSH will not have a path to the resource.
Newt is missing or not running properly
Make sure Newt is installed, up to date, and running with the correct site ID, secret, and endpoint.
The certificate expired before login started
The SSH certificate is valid for 5 minutes to begin the session. If you wait too long before connecting, just run the command again.
This guide covered the simplest Pangolin SSH pattern: the host running Newt is also the host you are SSHing into.
If you want that Newt-connected site to help you reach other local SSH devices on the same network, the architecture changes. In that model, Newt stays on one site host and each target device runs the Pangolin auth daemon.
That is a separate guide because it introduces a different connection path, different service placement, and extra network considerations.
Do I need separate SSH keys for Pangolin SSH?
No. Pangolin generates a temporary key pair and uses a short-lived signed certificate for each session.
Do users connect to the site directly?
No. Users connect to a private resource on the site. Newt provides the connectivity, but access to the resource is what determines whether a user can get a certificate and start a session.
Do I need to expose SSH publicly for this to work?
No. In this setup, users reach the host over the Pangolin connection to the private resource. You still need to allow the SSH port in the resource configuration, but that is not the same as exposing SSH publicly to the internet.
Do I need to run the auth daemon separately on the same host as Newt?
No. In this setup, Newt runs with --auth-daemon and provides that functionality on the same machine.
Is the SSH session proxied through another host in this setup?
No. In a same-host setup, the client reaches the host running Newt over the Pangolin path, and Newt forwards the connection locally to the SSH service. There is no extra SSH hop through another internal machine.
How are usernames created on the remote host?
Pangolin derives the username from the part of the user’s identity before the @. If that name is already taken, Pangolin adds a numeric suffix until it is unique.
