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.
dotnet new trakhound.apidotnet run on your computerth packages dotnet makes a .thp/greeter answers--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.
Before You Start
- The .NET 10 SDK
-
A TrakHound Instance. On Windows, download the installer and keep the defaults (a Windows Service on port
8472). The installer asks you to create the admin account. On Linux, use the release archive'sinstall.sh(see Installation). - The TrakHound CLI (
th), used to build Packages (download the installer)
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.defaultRouteisgreeter, 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.mdandCLAUDE.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
- In the admin UI, open Packages and select the Upload tab.
- Drop
Greeter-0.0.1.thponto 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.
--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
| Problem | What 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
dotnet new trakhound.app.
Functions & Scheduling
Run code on demand, with Jobs, or on a schedule.
Build with AI Tools
Create and change modules with Claude Code and other AI coding tools.
Connect AI Assistants
Turn on the MCP Server so AI assistants can use your Instance and your APIs.