Import hosts from a cloud

Cloud import reads the machine list of a cloud or infrastructure account through that provider’s read-only API and adds the machines as hosts. Your device talks to the provider directly: nothing goes through ZestSSH’s servers, and the token you give is used for the scan only unless you choose to keep the account in sync.

Cloud import works on phones and computers, on every plan.

Sources

Source	What it reads	What it needs
AWS EC2	Instances in every region you use, or the regions you name	An access key that can only read: `ec2:DescribeInstances` and `ec2:DescribeRegions`
DigitalOcean	Droplets in your account	A personal access token with only the `droplet:read` scope
Hetzner Cloud	Servers in one project	A project API token with Read permission
Azure	Virtual machines in your subscriptions	A service principal with the Reader role, or an access token from `az account get-access-token`
Tailscale	Every device on your tailnet, or every node of a Headscale server	An OAuth client secret with the `devices:core:read` scope, or an API access token; for Headscale, a Headscale API key
Proxmox VE	VMs, containers and nodes of a cluster	An API token with the PVEAuditor role

The same Import hosts dialog also lists, under From another app: SSH config file, PuTTY sessions (on Windows), MobaXterm, SecureCRT, Termius, CSV file, ZestSSH host file, Paste a share link and Paste a list. Below the list, Need to import something else? has Let us know. See Importing from other apps and Import hosts from a CSV file.

Import from a cloud

Open Import hosts:

On a computer: on the Hosts page, open the menu beside New host (More ways to add) and choose Import hosts. It is also in the command palette (Import hosts), and on a Mac under File > Import hosts.
On a phone: open More > Settings > Data > Import data and choose Hosts from a cloud.

Then:

Under Cloud and infrastructure, choose the provider. The dialog moves on to its fields.
In Account name, give the account a name, for example “AWS production”. Imported hosts show it as “From AWS production”.
Fill in the provider’s fields. Open How to make one for the steps to make a token that can only read, with the policy or commands to copy.
Decide on Keep in sync (see Keep an account in sync). It is off unless you switch it on.
Choose Connect and scan.
In Choose hosts, tick the machines to import (see The list of machines), then Next.
In Destination, under Where they go, choose Personal (in a team, a vault can be chosen instead). Pick a key in Sign in with and a Group, then choose the import button, which names how many hosts it imports (for example Import 3 hosts).

ZestSSH then says how many hosts came from the account. If some could not be written, it lists them with Copy details.

What each provider asks for

AWS EC2: Access key ID, Secret access key, Session token (only temporary keys have one, as from IAM Identity Center) and Regions (leave it empty for every region the account has turned on, or name some, like us-east-1 eu-west-1).
DigitalOcean and Hetzner Cloud: Token.
Azure: Tenant ID, Client (application) ID and Client secret of a service principal. Instead of all three, you can paste an access token from az account get-access-token into Client secret. Subscription ID is optional: leave it empty for every subscription the credentials can read.
Tailscale: Token, an OAuth client secret (tskey-client-...) or an API access token (tskey-api-...). The app’s own steps suggest the OAuth client, since an API access token can also change your tailnet. Leave Control server empty for Tailscale.
Headscale: choose Tailscale, put your Headscale server’s address in Control server (for example https://headscale.example.com), and a Headscale API key, from headscale apikeys create, in Token. A Headscale server is reached over https:// only.
Proxmox VE: Proxmox address, the https address you open Proxmox at (port 8006 when you give none), and API token, written as USER@REALM!TOKENID=SECRET, for example root@pam!zestssh= followed by the secret. A PVEAPIToken= in front of it is fine.

Proxmox certificates

Proxmox makes its own certificate, so the first scan usually stops at Check this certificate. It shows the certificate’s SHA-256 fingerprint. Compare it with the one Proxmox shows under the node’s System > Certificates (pve-ssl.pem), or with what pvenode cert info prints on the node. Paste that fingerprint into Compare and ZestSSH says They match or They do not match: do not trust it. Choose They match, trust it only when they match.

A kept account remembers the certificate you confirmed. If Proxmox later answers with another one, the check stops and says the certificate is not the one you confirmed, with both fingerprints in its details.

The list of machines

Choose hosts says how many machines the account lists. Each row shows the machine’s name, the address it would get, where it runs, and a status:

Status	What importing does
New	Adds it. Ticked to begin with.
Already here	A host with this address is here already. Ticking it links that host instead of adding another. Not ticked to begin with.
Imported	Imported before and unchanged: nothing to do.
Update	The provider gives a new address or name. Importing updates what you have not changed yourself.
No SSH	A phone, a tablet or Windows, which usually has no SSH server. Not ticked; tick it if this one has one.
No address	The provider gives no address to connect to. It cannot be imported.
No longer listed	Imported from this account before. It is marked, not removed.

When machines have both a public and a private address, Use private addresses switches the list to the private ones, for machines you reach over a VPN or through a bastion.

What comes over

Each new host gets:

the machine’s name as its label, or its address when it has no name,
its address, port 22 and SSH as the way to connect,
the key you chose in Sign in with, or none, so ZestSSH asks when you connect (Ask when connecting),
the group in Group (the account name to begin with; found by name or made, or none when empty),
the provider’s tags, up to 12, as lowercase key:value tags,
a mark saying which account it came from. The mark syncs with the host, so a later import finds the same host by the provider’s own id for the machine, and a new address updates the host instead of adding another.

Per provider:

AWS EC2: the Name tag is the host’s name, or the instance id where there is none. Terminated instances and ones shutting down are left out, and so are AWS’s own aws: tags.
Tailscale: devices waiting for an admin’s approval are left out.
Proxmox VE: a running VM’s address comes from its guest agent and a running container’s from its interfaces; otherwise a static address in its settings is used. A VM on DHCP without a guest agent has no address. Templates are left out. The cluster’s nodes are listed too. Reading guest agent addresses also needs VM.GuestAgent.Audit (Proxmox VE 9) or VM.Monitor (Proxmox VE 8).
Stopped machines are listed and marked “stopped”.

What does not come over

No user names, passwords or keys. The provider’s sign-in details are not imported. You pick a key that is already in ZestSSH, or let ZestSSH ask when you connect. The Destination step gives a hint: DigitalOcean and Hetzner machines usually sign in as root, on AWS the user depends on the image (ec2-user on Amazon Linux, ubuntu on Ubuntu, admin on Debian), and each Azure VM signs in as the admin user it was made with.
No other ports. Every host is added on port 22. Change the port in the host editor where a machine listens elsewhere.
No duplicates. A machine whose address is already a host here (on port 22) is shown as Already here, never added twice.
No deletions. A machine the account no longer lists is marked No longer listed; its host stays until you delete it.
No tokens in sync. The token is never synced and never sent to ZestSSH.

On a computer, hosts from a cloud show a small cloud icon on their card in the Hosts page; its tooltip says “From” and the account’s name. Once the account no longer lists the machine, the icon is crossed out and its tooltip says “No longer listed by” and the account’s name.

Keep an account in sync

With Keep in sync on, ZestSSH checks the account every 30 minutes while ZestSSH is open and unlocked on this device, the first time a minute after you unlock it. A check:

adds new machines that look like they run SSH,
updates a changed address or name, where you have not changed it yourself,
marks machines the account no longer lists.

A check never links a host that only shares an address, and never adds phones, tablets or Windows machines: import again by hand for those.

The token stays on this device, locked in the system keychain. It is never synced and never sent to ZestSSH, so each device checks only the accounts it keeps itself. If the keychain cannot take the token, the hosts are still imported and ZestSSH says Imported, but not kept in sync.

Kept accounts are listed under Cloud accounts:

On a computer: Settings, General, under Data.
On a phone or a tablet: More > Settings > Data.

Each shows where its hosts go, when it was last checked, how many machines it found, and why the last check failed where it did, with Copy details. Check now checks it at once. Stop and forget, in the menu beside it, asks first, then deletes the token from this device and stops the checks; the hosts it imported stay, still marked where they came from.

How your token is protected

ZestSSH contacts only the provider’s own API addresses (for Proxmox and Headscale, the address you give), never follows a redirect, and sends tokens only over https.
Every request times out after 25 seconds, an answer larger than 16 MB is refused, and a scan reads at most 100 pages of a list.
Names from a provider are cleaned of control and direction characters and shortened to 80 characters, and addresses are checked before they are used: anything that is not an address, and loopback and link-local addresses, are dropped.
When something fails, Copy details gives what was asked and what came back, with every token and secret replaced by [hidden].
With Recording mode on, ZestSSH asks before it shows the fields you type tokens into, and machine names and addresses in the list are masked.

Limits

Importing into a team’s vault is offered only for vaults whose rules let you add hosts. See Teams Overview.
The list shows what the token may read. A token limited to one project, subscription or region imports only that.

Next steps

Import hosts from a CSV file for hosts kept in a spreadsheet.
Install a key on hosts once the hosts are in, so a key can sign in to all of them.
Cloud sync to take the imported hosts to your other devices.