# Import tunnels

To add more than a handful of servers, go to **Tunnels**, click **Add tunnel**, and open the **Bulk import** tab. You can paste configs for AI to sort, upload config files, or upload a [TunnelHQ export file](#import-a-project-export).

## Paste and let AI sort it

The **Paste Text** tab is AI-assisted. Paste whatever you have, whether that's clean share links, full config files, or a block of text copied from an email, and TunnelHQ works out which entries are tunnels.

<Steps>

1. **Paste your configs.**

   Share links (`vless://`, `vmess://`, `trojan://`, `ss://`, `hysteria2://`, `tuic://`), WireGuard and OpenVPN config text, and plain `host:port` lines all work. You can mix protocols, one per line or in bulk.

2. **Click Analyze with AI.**

   TunnelHQ detects the protocol of each entry and extracts its host, port, and settings.

3. **Review the detected tunnels.**

   Each row in the preview is marked **ready**, **needs input**, or **cannot import**. Entries missing a credential, such as an OpenVPN password, are marked so you can fill them in before importing.

4. **Import.**

   Click **Import N tunnels**. Only rows marked **ready** are imported, and each one's first check is queued.

</Steps>

:::note[Messy input is fine]
Duplicate lines, surrounding text, and mixed protocols are expected. The AI step extracts the tunnels and ignores everything else.
:::

## Upload config files

The **Upload Files** tab accepts OpenVPN (`.ovpn`) and WireGuard (`.conf`, `.wg`) config files, and a TunnelHQ export file (`.json`), described [below](#import-a-project-export). Drag them onto the drop zone, or click it to browse.

| Protocol | File types |
| --- | --- |
| OpenVPN | `.ovpn` |
| WireGuard | `.conf`, `.wg` |

Each file can be up to **1 MB**, and you can select several at once. TunnelHQ parses each file, detects the protocol, and extracts the connection details. If a file needs a credential, for example an OpenVPN config without an embedded username and password, you're asked for it before the import completes.

:::caution[Other file types are skipped]
Only `.ovpn`, `.conf`, and `.wg` files and TunnelHQ export files are accepted. Other files, and files that can't be parsed, are skipped with a message, so nothing is left out silently.
:::

If you switch projects while the Import dialog is open, it closes, so nothing is imported into the wrong project.

## Subscription URLs

If your provider gives you a subscription URL, TunnelHQ can add its servers and keep them in sync, so your tunnels follow the provider when it rotates endpoints.

Paste the subscription URL into **Add tunnel**. The dialog shows **Subscription URL detected** and previews the configs behind it. Choose the settings and save; TunnelHQ confirms with "Subscription URL saved. Sync started."

| Setting | Options |
| --- | --- |
| Sync interval | Every 5 minutes, 15 minutes, 30 minutes, 1 hour (the default), 2 hours, 6 hours, 12 hours, or 24 hours. |
| Engine | **Auto (Both)** (the default) races both engines, so configs such as xhttp get tested by Xray-core. Or choose **sing-box** or **Xray-core**. |
| Timeout (seconds) | How long each config's test may take. Default 30. It also becomes the timeout of every tunnel the subscription creates. |
| Max workers | How many of the subscription's configs are tested in parallel. Default 5. |

Tunnels from a subscription are tested each time it syncs, so their check interval is the sync interval, rather than a schedule of their own.

When you edit an existing subscription, its settings form offers a different list of sync intervals: 5, 10, 15, or 30 minutes, or 1, 2, or 6 hours. A subscription set to 12 or 24 hours shows its interval there as "(custom)".

:::caution[Subscription URLs need a paid plan]
The Free plan can't add subscription URLs. Starter includes 3, Pro 10, and Business unlimited.
:::

## Import a project export

A project export is one file with a project's tunnels, Uptime checks and subscriptions. To make one, go to **Settings**, then **Advanced**, and click **Export Project Data** under **Data Export**. The file holds each tunnel's stored login, so keep it as safe as a password.

To import an export into the project you're in, do either of these:

- Go to **Settings**, then **Advanced**, and click **Import Project Data** under **Data Import**.
- In **Add tunnel**, open **Bulk import**, then **Upload Files**, and choose the file.

TunnelHQ reads the file first, then asks whether to import it into the project and shows how many tunnels, Uptime checks and subscriptions it holds. Click **Import N** to add them. When it finishes, it lists anything that wasn't added, with the reason, and anything that was already in the project.

- **Nothing is replaced.** A tunnel or check with the same name and kind as one already in the project is skipped. Nothing in the project is changed or removed.
- **Tunnels need the same TunnelHQ server.** Each TunnelHQ server encrypts logins with its own key, so a tunnel comes across only when you import the file on the TunnelHQ server that made it, such as app.tunnelhq.com. A tunnel from another server is listed as not added; add it again from its config.
- **Subscriptions come with a new export.** An export brings the project's subscriptions and leaves out the tunnels they make. Each subscription brings its tunnels back at its first sync, within a few minutes. Adding a subscription needs a role that can edit the project, and a free subscription on your plan. An older export has no subscriptions, so the tunnels they made are listed as not added: export the project again.
- **Checks start at once.** Uptime checks keep their settings and start checking straight away. A check's request headers, body and basic auth login aren't in the file, so add them again. A heartbeat gets a new address, so point your job at it.
- **Your plan still applies.** Tunnels count toward your plan's tunnel limit, and Uptime checks are free while Uptime is in beta. A tunnel or check set to run more often than your plan allows is checked at your plan's fastest interval instead.
- **Limits.** One import takes up to 1,000 tunnels, checks and subscriptions, from a file of up to 5 MB. Importing needs a role that can add tunnels, and exporting needs a role that can edit them.

## Which method to use

| You have | Use |
| --- | --- |
| A few servers | **Add tunnel**, one at a time (see [Working with monitors](https://site.dev.tunnelhq.com/docs/concepts/monitors/)) |
| A large batch of mixed configs | AI paste |
| A folder of config files | File upload |
| A provider link that changes over time | A subscription URL |
| A TunnelHQ export file | [Import a project export](#import-a-project-export) |