Tunnels
Manage names, keys and connections
Read a tunnel’s state, stop it safely, rotate or revoke its keys without downtime, rename it, delete it, and keep its client up to date.
Read the connection state
#Open a tunnel from Tunnels to see its state:
- Connected: a client is connected. It does not prove your local app is healthy.
- Disconnected: no client is connected. The name and key stay as they are, and visitors see a page saying the tunnel’s computer isn’t connected.
- Revoked: the tunnel has no usable key until you rotate it or add a key.
Stop a tunnel without losing it
#Press Ctrl+C in the CLI or stop your AppHost. The tunnel goes Disconnected and keeps its name, address and key, so you can connect again later.
A second client that connects with the same name replaces the first. To run tunnels from two computers or two AppHosts at once, give each its own tunnel.
Choose an action and prepare the recovery
#Open the tunnel and choose More actions (on a phone, the Tunnel actions button). Each action disconnects the client, so plan the next step first.
| Action | What happens | What to do next |
|---|---|---|
| Rotate key | Every existing key stops working at once and the client disconnects. | Save the new key, which is shown once, update your client, and reconnect. |
| Revoke all keys | The client disconnects and the tunnel keeps its name with no usable key. | Rotate the key when you want to connect again. |
| Rename | The public address changes and the client disconnects. | Update the client’s tunnel name, webhook addresses, sign-in callbacks and allowed hosts. |
| Delete tunnel | The key stops working and the name becomes free for anyone on the service. | Retire old links. A tunnel created again with the same name is a new tunnel. |
To change keys while the tunnel stays online, add a second key instead of rotating.
Owners can do everything, including rename. The member who created a tunnel can add, rotate or revoke its keys, delete it, and change body capture. Other members can view and use it. The menu shows only the actions you can take.
Reconnect after a key change
#- Save the new key privately.
- For the CLI, set GROUNDHOG_KEY again in the same terminal and run your command again.
- For Aspire with WithGroundhogTunnel, update Parameters:groundhog-<tunnel name>-key in your AppHost’s user secrets. The explicit AddGroundhogTunnel form uses the secret parameter you declared instead. Then use Reconnect on the stopped tunnel resource or restart the AppHost. Reconnect is unavailable while the client is connected or retrying.
- Check the tunnel shows Connected, open its public address, and check a new request reaches your app.
Replace a connection key without downtime
#Replacing every key at once leaves the tunnel offline until you update the agent. To change keys on your own schedule, give the tunnel a second key, move the agent to it, then revoke the old key. The address is unavailable only while the agent restarts. A tunnel can have 2 connection keys at a time.
On the tunnel’s Settings tab, Connection keys lists each key by the first 8 characters of its ID and when it was created. A key shows Connected while an agent uses it, and otherwise when it was last used, or Never used.
- Choose Add key, then Add key to confirm. Save the new key, which is shown once. The current key keeps working and the agent stays connected.
- Put the new key where the agent reads it and restart the agent, as in Reconnect after a key change.
- In Connection keys, check the new key shows Connected and the old key doesn’t.
- Choose Revoke on the old key and confirm. Only an agent still using that key disconnects.
With the CLI, signed in with groundhog login, the same steps for a tunnel named my-tunnel are:
groundhog key add my-tunnel
groundhog key list my-tunnel
groundhog key revoke my-tunnel 8b27e4d1f0c94a3b9e6d5c2a1f087e43groundhog key add saves the new key on this computer in place of the key saved for my-tunnel, so the next groundhog host my-tunnel uses it. With --project AppHost/AppHost.csproj it also writes the key to the AppHost’s user secrets as Parameters:groundhog-tunnel-key. 8b27e4d1f0c94a3b9e6d5c2a1f087e43 is the old key’s ID, as groundhog key list my-tunnel prints it. See Manage connection keys for every key command.
Recover after an interrupted change
#Refresh the tunnel list before repeating a change that failed or lost its response. A change already accepted by Groundhog can finish while you reconnect. Competing changes can be refused, and the tunnel can be temporarily unavailable while the change finishes.
If creation or key rotation finished but you never received its key, rotate the key again and update your local client. If adding a key finished but you never received it, revoke that key in Connection keys and add another. Existing keys cannot be shown again. If a rename finished, use the new name and update your app’s registered callbacks.
If the tunnel stays unavailable, share the failed action and error text with Groundhog support. Keep connection keys and private request content out of your report.
Understand client update hints
#The tunnel’s page shows the connected client’s package and version when the client reports them. On a disconnected tunnel this is the version last seen, not a check of a running client.
When a newer release is known, the page shows an update command. An unknown version, or a failed lookup, does not mean an update exists.
Apply the update, restart the client, then check its new version and a successful request. Updating an AppHost package does not change the sample’s own code; see Aspire asks for extra parameters.