Provision Connections from a URL¹

WebSSH can read a small JSON file listing connections from a URL, create these connections, and keep them up to date each time the app is opened. You describe your servers once, in one file, and every device follows.

It is made for:

a fleet of iPhone, iPad or Mac managed with an MDM (Microsoft Intune, Jamf, Kandji…), where each device must come with the connections of the organization;
a team sharing the same list of servers;
a list of servers generated by a tool (Terraform, Ansible, a script) that your own devices should follow.

WebSSH PRO

Reading connections from a URL, and importing a connections file, require WebSSH PRO on the device. Exporting your connections to a file is free.

How it works

You write a connections file and host it on an HTTPS URL.
You give that URL to WebSSH: with your MDM, with a link, or in Settings.
WebSSH reads the file, creates the connections that are missing and updates the ones it created before.
Later, you edit the file: the devices pick the change up at the next launch.

Passwords and private keys are never part of the file behind a URL: each user enters their own credentials once on the device.

The connections file

A JSON file, UTF-8, 1 MB at most:

{
  "version": 1,
  "connections": [
    {
      "id": "prod-web-01",
      "name": "Production web 01",
      "host": "10.0.0.5",
      "port": 22,
      "user": "deploy",
      "group": "Production",
      "tags": ["web", "nginx"],
      "roles": ["SSH", "SFTP"],
      "key": "Deploy key"
    },
    {
      "id": "backup-nas",
      "name": "Backup NAS",
      "host": "nas.example.lan",
      "port": 2222
    }
  ]
}

Field	Required	Value
`version`	Yes	`1`
`connections`	Yes	The list of connections. It may be empty
`id`	No	What ties a connection of the device to this entry. Any text, unique in the file. Without it, the `name` plays that role. Keep it stable: a changed `id` is another connection
`name`	Yes	Name shown in the list
`host`	Yes	Host name or IP address
`port`	No	`1` to `65535`. `22` when the connection is created
`user`	No	User name
`group`	No	Folder of the connection
`tags`	No	List of tags
`roles`	No	Among `SSH`, `SFTP`, `SCP`, `TELNET`, `MOSH`, `PROXMOX`. `SSH` and `SFTP` when the connection is created
`key`	No	Name of an SSH key that already exists on the device

A few rules worth knowing:

A field you leave out is not managed. It takes its default when the connection is created, then WebSSH leaves it as it is on the device. Leave user out, for example, when each person has their own account: what they type stays.
Unknown fields are ignored, so your tooling may add its own.
An invalid entry is skipped alone (no name, no host, a port out of range…): the other entries are still applied.
password, privateKey and passphrase are refused behind a URL: the whole file is rejected. Credentials never travel that way.
The key is only assigned when the connection has no key yet: a key chosen on the device is never replaced.

Start from your own connections

You do not have to write the file by hand: export your connections from a device that already has them, then edit the result.

Where to host the file

Anywhere that serves it over HTTPS: an intranet server, SharePoint, Azure Blob Storage, an S3 bucket, a private Gist…

http:// is refused, and so is a redirection to http://.
The file holds no secret, so a hard-to-guess URL is a reasonable protection when it has to be reachable from the Internet.
The devices must be able to reach the URL: a file on your intranet is only read on the company network or through your VPN.
The file must be plain JSON: an encrypted connections file is not accepted behind a URL.

Give the URL to WebSSH

There are three ways. A URL set by an MDM always wins over the two others.

With an MDM (Microsoft Intune, Jamf…)

WebSSH reads its configuration from the Managed App Configuration of the device, the standard channel every MDM uses to configure an app:

Key	Type	Value
`provisioningURL`	String	The HTTPS URL of your connections file

Microsoft Intune: Apps > App configuration policies > Add > Managed devices, platform iOS/iPadOS, targeted app WebSSH. In the configuration settings choose Use configuration designer and add the key provisioningURL, value type String, with your URL as value. Assign the policy to your devices.
Jamf and others: in the App Configuration of WebSSH, use this property list:

<dict>
    <key>provisioningURL</key>
    <string>https://example.com/webssh-connections.json</string>
</dict>

A URL coming from the MDM is applied without any confirmation on the device, and cannot be changed in the app. When the MDM changes or removes the key, WebSSH follows.

With a link

Send or publish a link of this form; tapping it on the device registers the URL:

webssh://provision?url=https%3A%2F%2Fexample.com%2Fwebssh-connections.json

The URL of the file is the value of url, percent-encoded. WebSSH shows the URL and asks for a confirmation the first time; after that the file is read silently.

In Settings

Open WebSSH Settings
Go to Maintenance > Provisioning
Type the URL and save it

The same screen shows when the file was last applied, what happened, and the last error if any.

When is the file read?

When the URL is registered, and each time you press Apply now in Settings > Maintenance > Provisioning.
When the app is opened or comes back to the foreground, at most once every 15 minutes.

When the URL cannot be reached (no network, server down, device off the company network), nothing happens: the connections already created stay as they are, and the next attempt will do. The reason is shown on the Provisioning screen.

What WebSSH does with the file

An entry with no matching connection is created.
A connection created from the file is updated when its entry changes. It is recognized by its id, not by its name or host.
The connections you created yourself are never touched, even when they point at the same host.
Passwords, keys and every setting that is not in the file (theme, startup command, notes…) stay as they are on the device.
You may move the file to another URL: as long as the id values are the same, the connections follow instead of being created a second time.

When an entry is removed from the file

Nothing is deleted silently. WebSSH lists the connections that are no longer in the file and lets you remove them or keep them as ordinary connections. Closing that sheet changes nothing: the question comes back later.

Export and import a connections file

Settings > Maintenance > Provisioning also writes and reads the same file format, which is handy to prepare the file of a fleet, or to move connections from one device to another.

Export connections… saves webssh-connections.json in the folder you choose. Two options:

Include passwords and private keys: off by default. Without it the file never contains a credential, and it can be served as a provisioning URL as it is.
Encrypt the file: the file becomes webssh-connections.wsbk, protected by your database password or by a password you choose for this export. It is the same container as the encrypted backups.

A file with credentials in clear

With the first option on and the second one off, the file holds your passwords, private keys and passphrases as readable text. WebSSH asks you to authenticate and to confirm. Store and transmit such a file accordingly, and never serve it as a provisioning URL.

Import connections… reads a file exported by WebSSH, or written by hand, and shows how many connections it would create and update before doing anything. An encrypted file opens by itself when it was protected by the database password of the device; otherwise its password is asked. A file read this way may carry credentials: they are imported with the connections.

The same exists in mashREPL: see webssh export json and webssh import json.

When the secrets of the database are locked

If you turned on Encrypt Secrets and the secrets are locked on this device, an export with passwords and an import of a file carrying passwords are refused until you unlock them in Maintenance > Local Database. Everything else keeps working.

Troubleshooting

The Provisioning screen shows the last error. The most common ones:

Message	What to check
The provisioning URL must start with https://	The URL, or a redirection of the server, uses `http://`
Unable to fetch the file	The device cannot reach the URL (network, VPN), or the server answered an error such as `HTTP 404`
The file is not valid JSON	Open the file in a JSON validator; a web page (login form) served instead of the file gives the same message
Entry n carries the field "password"	Remove the credentials from the file: they are never read from a URL
The file served by this URL is encrypted	Serve the plain `webssh-connections.json`, not the `.wsbk` file
WebSSH PRO is required	The device does not have WebSSH PRO

Since WebSSH 33.4 (#1128). ↩

Last update: November 11, 2026

Provision Connections from a URL1