Import and Export
Download servers as a JSON file, and restore them in the same or another organization
Introduction
A server's configuration can be downloaded as a JSON file, and a JSON file can be imported to create servers. Use it to back up a server, copy servers between organizations (for example from a test organization to production), or move to a self-hosted installation.
All server types can be exported and imported except built-in servers, which every organization already has.
Exporting
There are two ways to export:
- One server: open the server's Settings tab and find Export as JSON.
- Several servers: on the servers list, select the rows to export, then choose Bulk actions and Export JSON.
Both open the same dialog, where you choose what goes into the file:
| Option | What it adds |
|---|---|
| Include sensitive fields | OAuth client secrets, Tailscale auth keys, and the values of environment variables and headers. When off, the names are kept and the values are blanked. |
| Include server-scoped credentials | The credentials stored on the server itself. Credentials owned by profiles or user accounts are never exported. |
| Include source code | The code package of Runnable Code servers. Shown only when the export contains one. |
Values like {{ credentials.keys.MY_API_KEY }} are always kept. They reference the credential store and are not secrets themselves.
The file can contain secrets in plain text
With the first two options on (the default), the file holds API keys, tokens and client secrets readably. Treat the file as a secret: store it safely and delete it when it has served its purpose.
The file holds configuration only. Deployment state, logs, and tool lists are not exported; the importing organization discovers tools on its own when the server deploys.
Importing
Open Add Server and choose Import from JSON, or use the Import button on the servers list. Pick the file, and the page lists every server in it for review before anything is created.
When a server in the file has the same slug as an existing server, you choose per server:
- Add it under a new slug (a numeric suffix such as
-2is proposed), or - Replace the existing server with the imported configuration.
Importing creates the servers, stores their server-scoped credentials, and uploads their source code. A server that is enabled in the file deploys right away. Servers that fail to import do not stop the rest; the result is reported per server.
After an import you may still have work to do:
- If sensitive fields were excluded from the export, the imported servers have their environment variable, header and secret values blank. Fill them in under the server's settings.
- Credentials owned by profiles or user accounts are not in the file. Users connect their own credentials again, as described on the credentials page.
Permissions
Exporting a server requires permission to change it, and exporting its stored credentials requires permission to read their secrets. Importing requires permission to create servers, and replacing an existing server requires permission to change that server. See Permissions and Roles.
Last updated on