Connect an app with the CLI

First create a tunnel. Then start the app you want to share and open its localhost address in your browser. Groundhog forwards requests; it does not start your app.

For a local address of http://localhost:3000, the port is 3000. Use your app’s real port.

Install the .NET 10 SDK, which includes the ASP.NET Core runtime the CLI needs, then run:

dotnet tool install --global Groundhog.Cli --version 0.4.0-preview.7
groundhog --version

If it is already installed, run groundhog update instead. Open a new terminal if your shell cannot find groundhog.

For Windows, macOS and Linux details, a per-repository install, updates and uninstalling, see Install and update the CLI.

groundhog

It opens on a launch screen with your version, your sign-in and how many tunnels are connected. Press Enter to continue to the menu, Q to quit, or U to install an update when one is shown.

Use the arrow keys to choose a screen and Enter to open it. Esc goes back and Q quits. The bar at the bottom lists the keys that work on the current screen. The menu includes Home, Tunnels, Running agents, Saved profiles, Workspaces, Diagnostics, Sign in and Help.

Choose Sign in to approve access in your browser. Tunnels lists tunnels in your selected workspace; Enter opens the tunnel detail. Account access follows your workspace role.

While hosting, press 1 for Overview, 2 for Requests or 3 for Statistics. Esc or Ctrl+C stops hosting. Redirected input/output or --no-interactive prints help instead of opening the full-screen app.

In the terminal you will run Groundhog from, enter the key at a hidden prompt, so it never appears in the command you type or your shell history.

$env:GROUNDHOG_KEY = Read-Host "Groundhog connection key" -MaskInput

The PowerShell command needs PowerShell 7.1 or later, which added -MaskInput. The variable lasts for this terminal session. Never put a key in a committed script, a screenshot, an issue or a --key argument.

groundhog host aspire-quickstart --port 3000 --verbose

Replace aspire-quickstart with your tunnel name and 3000 with your app’s port. The Groundhog service address is automatic in 0.4.0-preview.7.

1. 1Keep this terminal and your app running.
2. 2Check the tunnel shows Connected in the dashboard.
3. 3Open the tunnel’s public HTTPS address and check you see your app.
4. 4Press Esc in the interactive host view, or Ctrl+C in the Groundhog terminal, to disconnect.

A saved profile remembers which tunnel to host and where your app runs on this computer, so you can connect it with one command or one key in the app. It never stores a connection key.

groundhog profile save myapp --target http://localhost:3000
groundhog host myapp

The key comes from GROUNDHOG_KEY, or from this computer when you created the tunnel, added a key or rotated it while signed in to the CLI. In the app, Saved profiles lists your profiles: Enter hosts one in this terminal and B starts it in the background.

groundhog start myapp
groundhog ps
groundhog restart myapp
groundhog stop myapp

A background agent keeps forwarding after you close the terminal, until you stop it or sign out of your computer. groundhog profile list shows your profiles and groundhog profile delete myapp removes one; neither changes the tunnel itself. Profiles are kept in Groundhog’s folder.

Signed in with groundhog login, you can add, list and revoke a tunnel’s connection keys without opening the dashboard. Each command takes the tunnel’s name, here my-tunnel, and --workspace <slug> when the tunnel isn’t in your selected workspace.

groundhog key add my-tunnel
groundhog key list my-tunnel
groundhog key revoke my-tunnel 8b27e4d1f0c94a3b9e6d5c2a1f087e43
groundhog key revoke my-tunnel
groundhog key rotate my-tunnel

8b27e4d1f0c94a3b9e6d5c2a1f087e43 is a key ID that groundhog key list my-tunnel printed. key revoke asks you to confirm; scripts pass --yes. To move an agent to a new key while the tunnel stays online, see Replace a connection key without downtime.

Use --target with your app’s full local address instead of --port, for example --target https://localhost:7132. Trust your development certificate on this computer, or pass its certificate with --local-ca. Visitors get HTTPS either way, so your local app does not need it.

See Choose the local transport for certificate options.