Aspire

Your first tunnel with Aspire

Run the Aspire sample, enter your connection key, and check that the public address reaches your computer.

Check the prerequisites

Create a workspace and a tunnel first, and have the tunnel’s name and connection key ready.

Install the .NET 10 SDK and the Aspire CLI. The sample uses Aspire AppHost SDK 13.6.1, so use Aspire CLI 13.6 or later.

Check the installed tools

dotnet --version
aspire --version

The first command must report a 10.x version. You do not need the Groundhog CLI, a container or your own back end for this sample.

Commands wrap to fit a narrow screen. Use Copy beside a command to keep its original line breaks.

Download the current sample

Download and open the released sample

git clone https://github.com/Unifinity-Software/groundhog-client.git
cd groundhog-client
git checkout 006ded02b6ba08dda5193325b806fc7b08b69eae
cd samples/AspireQuickstart

The checkout selects the source for client 0.4.0-preview.7, so changes on the repository’s default branch cannot silently change these instructions. The sample folder contains AppHost and Web.

This guide uses client 0.4.0-preview.7. Restarting an older copy does not update its code: older samples ask for 2 or 3 parameters, this one asks for 1. Download a fresh copy into a new folder if you have local edits to keep.

Start Aspire and enter the key

In AppHost/Program.cs, replace aspire-quickstart in WithGroundhogTunnel with the tunnel name you created. Use the name only, without a URL or domain.

Start the AppHost

aspire start --apphost AppHost/AppHost.csproj

Open the dashboard link Aspire prints. It asks for one secret parameter:

Aspire parameters
Parameter	What to enter
groundhog-aspire-quickstart-key	The connection key you saved for aspire-quickstart. If you changed the name, the parameter is groundhog-<your tunnel name>-key.

Turn on Save to user secrets, then submit. Aspire remembers the values on this computer, outside your repository, so it does not ask next time. User secrets are not encrypted; leave the toggle off if you would rather enter them each time.

The Groundhog service address and your web app’s local endpoint are automatic: there is no relay parameter and no port to enter.

Validate the complete connection

Wait until both web and web-tunnel show Running in Aspire.
In the Groundhog dashboard, check the tunnel shows Connected.
Open the public HTTPS address from the tunnel’s page, not the web app’s localhost address.
Check the response contains "message": "Hello through Groundhog".

Expected response

{
  "message": "Hello through Groundhog",
  "publicOrigin": "https://aspire-quickstart.groundhog.unifinity.com",
  "host": "aspire-quickstart.groundhog.unifinity.com"
}

Your hostname matches the address on the tunnel’s page. That response shows a visitor’s request reached your computer through Groundhog, and the tunnel’s console in Aspire shows the request too.

Stop and restart the sample

Stop the sample

aspire stop --apphost AppHost/AppHost.csproj

The public address stops serving when the client disconnects, and the tunnel name stays reserved until you delete the tunnel. Start the AppHost again to reconnect; saved user secrets mean no new prompt.

Add a tunnel to your own AppHost

Once the sample works, follow Add Groundhog to your AppHost to expose your own app. For an API gateway in front of internal services, see Tunnel a gateway to internal services. For a team where each developer runs their own tunnel, see Give each developer their own tunnel.

If something does not work, see Troubleshooting your connection.