# Standalone Hosts

> Run an API, Worker, or Function without an Instance, as a console app, service, IIS application, or container.

URL: https://www.trakhound.com/docs/trakhound-framework/standalone-hosts

A Package runs on an Instance, but an API, a Worker, or a Function can also run on its own: as a console app, a Windows Service, a Linux (systemd) service, an IIS application, a container, or a cloud web app. A host project runs it with the standard .NET host, and the Package project itself doesn't change, so the same code can still be installed on an Instance.

Diagram: One Package project can be installed on an Instance, or run by a host project that th host create makes next to it. The host runs the API, Worker, or Function as a console app, a Windows Service, a Linux systemd service, an IIS application, a container, or a cloud web app, and its Client can still connect to an Instance for Services and Functions.

Use a standalone host when a module needs to run where there's no Instance, for example:

- An API in a cloud web app or a container platform your organization already uses
- A Worker on a PC next to a machine, as a Windows Service or systemd service
- A Function run by Task Scheduler, cron, or a container job

## Create a Host

In the Package project's folder, run:

```
th host create --api-key
dotnet run --project ../MyCompany.MyApi.Host
```

`th host create` creates a host project next to the Package project, named after it with `.Host`. It picks the kind of host from the Package's category, finds the module class, copies `trakhound.debug.json` into the host's `appsettings.Development.json`, and with `--api-key` generates an API key for an API host, adds its hash to `appsettings.json`, and prints the key. Or create it with the template:

```
dotnet new trakhound.host -n MyCompany.MyApi.Host --module MyCompany.MyApi --kind api
```

`--kind` is `api`, `worker`, or `function`. The host has a `Program.cs`, its settings in `appsettings.json`, and a `Dockerfile` (build it from the parent folder: `docker build -f MyCompany.MyApi.Host/Dockerfile .`).

## API Hosts

An API host's `Program.cs`:

```
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddTrakHound(builder.Configuration.GetSection(TrakHoundHostOptions.SectionName));
builder.Services.AddTrakHoundApiKeyAuthentication();
builder.Services.AddHealthChecks().AddTrakHoundInstance();
builder.Services.AddWindowsService(); // Runs as a Windows Service or a systemd service when started as one
builder.Services.AddSystemd();

var app = builder.Build();
var api = app.MapTrakHoundApi(typeof(Controller).Assembly);
api.Group.RequireAuthorization(); // Every endpoint and stream needs an API key
app.MapTrakHoundOpenApi(api);     // The OpenAPI document at /openapi.json
app.MapHealthChecks("/health");
app.Run();
```

- `MapTrakHoundApi` creates the API's controllers and maps their endpoints and streams the same way the Instance does.
- Callers send one of the host's API keys in the `X-API-Key` header (or `Authorization: Bearer {key}`). These aren't the Instance's API keys, and an API host refuses every request until it has one. Any other ASP.NET Core authentication can be added instead.
- The host serves its OpenAPI document at `/openapi.json`, named and versioned from the Package, and a health check at `/health`.

## Worker and Function Hosts

- **Worker** - `AddTrakHoundWorker<Worker>()` starts the Worker when the host starts, and stops it when the host stops.
- **Function** - `RunTrakHoundFunction<Function>()` runs the Function once, writes its response (JSON) to the console, and exits with 0 when the run succeeds, for Task Scheduler, cron, or a container job. `MapTrakHoundFunction<Function>("/run")` runs it for each POST instead.
- **Service** - `AddTrakHoundService<Service>()` adds a Service for your own code to call.

## Settings

The settings are the `"TrakHound"` section of `appsettings.json`, environment variables (ex. `TrakHound__InstanceUrl`), or the command line (ex. `--TrakHound:Parameters:interval=1000`):

```
{
  "TrakHound": {
    "InstanceUrl": "https://instance.example.com",
    "ApiKey": "...",
    "ConfigurationId": "barcodes",
    "ApiKeys": [ { "Name": "line-1", "Hash": "..." } ],
    "Parameters": { "interval": "1000" }
  }
}
```

| Setting | What it does |
| --- | --- |
| `InstanceUrl` | The Instance the `Client` connects to. Without it, the module runs on its own and every `Client` call fails with an error that says so |
| `ApiKey`, `BearerToken` | Credentials for the Instance |
| `ConfigurationId` | The module's configuration ID (`default` when not set) |
| `VolumePath`, `VariablesPath` | Where the Volume and Variables are kept, relative to the application's folder |
| `Parameters` | The configuration parameters. Values are strings, and `GetParameter<T>` converts them |
| `ApiKeys` | API hosts: the keys callers send. Each has a `Name` (the signed in user) and the key's SHA-256 hash in `Hash`, or the key itself in `Key` when it comes from a secret store |
| `Input` | Function hosts: the input parameters of the run |

The host connects to the Instance when it starts. If it can't be reached, a warning is logged, the module still starts, and the health check reports **Degraded**. What the module logs goes to `ILogger`, so the host's log providers (the console, the Windows Event Log, or Application Insights) receive it.

## Compared with an Instance

A standalone host runs one module with only what the host project sets up. The Instance's admin UI, security profiles, Zones, metrics, and Package updates don't apply to it, so a module that many people use or that changes often is usually easier to manage on an Instance (see [Architecture for Plant Teams](https://www.trakhound.com/docs/trakhound-framework/architecture)).

> Not supported yet: Apps, Identity providers, and signing in with an Instance's users. An API host uses its own API keys, or any ASP.NET Core authentication you add.
