Get started
How Groundhog works
How a request reaches the app on your computer, which name, address and key does which job, and who can do what.
What Groundhog does
#Groundhog gives an app running on your computer a public HTTPS address. A visitor opens the address, the Groundhog service forwards the request to your computer, and your app sends the response.
The Groundhog client on your computer opens an outbound, encrypted WebSocket connection to the Groundhog service, which is also called the relay. Requests travel inside that connection, several at a time over HTTP/2, and responses come back the same way. Your computer needs no inbound firewall rule or router port forwarding.
Request and response bodies stream in both directions, and WebSockets and server-sent events work too. Groundhog forwards your app; it does not deploy it, so keep your app and the client running while you test.
Follow the four steps to a working tunnel
#Give each name and address the right job
#Groundhog uses five different values. Mixing them up is the most common reason a first connection fails.
| Value | Example | What it is for |
|---|---|---|
| Workspace address | web-team | Picks the workspace in dashboard paths such as /w/web-team/tunnels. |
| Tunnel name | shop-dev | Unique across the whole Groundhog service. You enter it in the client. |
| Public address | https://shop-dev.groundhog.unifinity.com | Where visitors reach your app. |
| Service address | https://groundhog.unifinity.com | Where the client connects to the relay. Normally automatic. |
| Local target | http://localhost:5173 | Where the client sends requests on your computer. |
Public addresses use only the tunnel name. Your workspace address never appears in them.
Understand the three kinds of access
#- Workspace membership comes from signing in to the dashboard. Every member can see the workspace’s tunnels and saved traffic.
- A connection key lets a client host one tunnel. It works independently of anyone’s sign-in.
- Visitors reach your app at its public address without a Groundhog account or a key.
Removing someone from a workspace does not change keys they already know: rotate those keys as well. See Remove a member.