# Quick Start

> Create an API, run it, install it on an Instance, and update it while it runs, in about 10 minutes.

URL: https://www.trakhound.com/docs/trakhound-framework/getting-started

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.

Diagram: Create a project from a template, run it on your computer, build a Package file, install it on an Instance, and call it. To change it, edit the code and build and install a new version, which the Instance loads without restarting.

## Before You Start

- The [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
- A TrakHound Instance. On Windows, [download the installer](https://applications.trakhound.com/TrakHound.Instance/latest/download?prerelease=true&source=website) 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's `install.sh` (see [Installation](https://www.trakhound.com/docs/trakhound-framework/installation)).
- The TrakHound CLI (`th`), used to build Packages ([download the installer](https://applications.trakhound.com/TrakHound.CLI/latest/download?prerelease=true&source=website))

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](https://www.trakhound.com/docs/trakhound-framework/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](https://www.trakhound.com/docs/trakhound-framework/debugging).

## 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](https://www.trakhound.com/docs/trakhound-framework/packages#publishing) 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

[Build a Sensor Dashboard Tutorial: build an application from a Worker, a Function, an API, and an App.](https://www.trakhound.com/docs/trakhound-framework/tutorials/sensor-dashboard) [APIs Routes, parameters, responses, streaming, permissions, and MCP Tools.](https://www.trakhound.com/docs/trakhound-framework/apis) [Call It from Other Languages Use your API from Python, JavaScript, C#, Rust, C++, or cURL.](https://www.trakhound.com/docs/trakhound-framework/clients) [Store Data Read and write Key-Values, Tables, Blobs, and Messages through Services.](https://www.trakhound.com/docs/trakhound-framework/services) [Build an App Create a Blazor user interface with `dotnet new trakhound.app`.](https://www.trakhound.com/docs/trakhound-framework/apps) [Functions & Scheduling Run code on demand, with Jobs, or on a schedule.](https://www.trakhound.com/docs/trakhound-framework/functions) [Build with AI Tools Create and change modules with Claude Code and other AI coding tools.](https://www.trakhound.com/docs/trakhound-framework/ai-tools) [Connect AI Assistants Turn on the MCP Server so AI assistants can use your Instance and your APIs.](https://www.trakhound.com/docs/trakhound-framework/mcp-server)
