Quick Start

Create an API, run it, install it on an Instance, and update it while it runs, in about 10 minutes.
Framework Docs Menu

In this guide you'll create an API, run it on your computer, install it on a TrakHound Instance, and change it while it runs. It takes about 10 minutes.

Createdotnet new trakhound.api
Rundotnet run on your computer
Buildth packages dotnet makes a .thp
InstallPackages > Upload on the Instance
Call/greeter answers
To change it: edit the code, build a new version (--version 0.0.2), and install it the same way. The Instance loads it without restarting, and the previous version stays installed so you can revert.
Steps 2 to 7 of this guide, in about 10 minutes.

Before You Start

Check that the Instance is running by opening http://localhost:8472/_admin and signing in with your admin account.

1. Install the Templates

dotnet new install TrakHound.DotNet.Templates

This adds a template for each kind of module: trakhound.api, trakhound.app, trakhound.function, trakhound.worker, trakhound.service, and trakhound.identity.

2. Create an API

dotnet new trakhound.api -n Greeter
cd Greeter

The project's Controller.cs has two GET endpoints:

public class Controller : TrakHoundApiController
{
    [ApiGet]
    public Task<TrakHoundApiResponse> Get([FromQuery] string name)
    {
        return Task.FromResult(Ok("Greeter : Get : " + System.DateTime.Now.ToString("o") + " : " + name));
    }

    [ApiGet("{name}")]
    public Task<TrakHoundApiResponse> GetWithRouteParameter([FromRoute] string name)
    {
        return Task.FromResult(Ok("Greeter : GetWithRouteParameter : " + System.DateTime.Now.ToString("o") + " : " + name));
    }
}

The project also has:

  • trakhound.package.json - The Package manifest. Its .defaultRoute is greeter, the route the API is served at once it's installed.
  • Program.cs - A debug host for running the API on your computer. It's left out of the Package.
  • trakhound.debug.json - The debug host's settings: the Instance it connects to (localhost:8472), credentials, and configuration parameters. It's left out of the Package.
  • AGENTS.md and CLAUDE.md - Instructions for AI coding tools such as Claude Code (see Building with AI Tools).

3. Run It on Your Computer

dotnet run

The debug host starts at http://localhost:5091. In another terminal (or a browser), call the endpoints:

curl "http://localhost:5091/?name=world"
Greeter : Get : 2026-10-26T19:30:04.7527961-04:00 : world

curl http://localhost:5091/world
Greeter : GetWithRouteParameter : 2026-10-26T19:30:04.8033097-04:00 : world

Or open the Api Debugger at http://localhost:5091/_debug to see and run the API's endpoints from the OpenAPI document the Instance will create for it, so a missing description or a wrong parameter type shows up before you install it.

Set breakpoints and debug it like any other .NET application. The debug host connects to the Instance in trakhound.debug.json (localhost:8472), so Client calls to Services and Functions work too. Stop it with Ctrl+C when you're done. To run it inside your Instance instead, with its routing and security, see Debugging & Testing.

4. Build the Package

th packages dotnet --output ./out

This builds the project and writes the Package file out/Greeter-0.0.1.thp.

5. Install It on the Instance

  1. In the admin UI, open Packages and select the Upload tab.
  2. Drop Greeter-0.0.1.thp onto the page (or click to select it), then click Install 1 Package.

The Instance installs the Package and adds a configuration for it at its default route, /greeter. You'll find it under Config > Api, where you can change its route, Volume, or parameters later.

6. Call It

curl "http://localhost:8472/greeter?name=world"
Greeter : Get : 2026-10-26T19:33:18.4610725-04:00 : world

curl http://localhost:8472/greeter/world
Greeter : GetWithRouteParameter : 2026-10-26T19:33:18.5224481-04:00 : world

In the admin UI, open Explorer > Api. /greeter is listed with its endpoints, request count, and response times. Click it to see its endpoints, run them from the browser, and read its logs.

7. Change It

Edit the first endpoint in Controller.cs:

[ApiGet]
public Task<TrakHoundApiResponse> Get([FromQuery] string name)
{
    return Task.FromResult(Ok($"Hello, {name}!"));
}

Build it as a new version, then upload and install out/Greeter-0.0.2.thp the same way as before:

th packages dotnet --output ./out --version 0.0.2
curl "http://localhost:8472/greeter?name=world"
Hello, world!

The Instance loads the new version without restarting, and both versions stay installed, so you can Revert to 0.0.1 from Packages > Installed.

Building on your computer doesn't change the version, so pass --version for each new build. When you publish to a Package server with th packages dotnet --publish, the next version is chosen for you.

Troubleshooting

ProblemWhat to do
The API returns 404, or Config > Api shows it as Not loaded Open Explorer > Diagnostics > Modules to see the load error. A Package built against a newer TrakHound version than the Instance doesn't load, so create projects with templates no newer than your Instance: dotnet new install TrakHound.DotNet.Templates::<version>.
The project doesn't compile (ex. ApiGet not found) The installed templates are older than these docs. Install the latest templates and create the project again.
th is not recognized Install the TrakHound CLI, then open a new terminal so the path is updated.

Next Steps