# Instances

> Run and configure the host application: settings, the admin UI, health checks, and CPU by Module.

URL: https://www.trakhound.com/docs/trakhound-framework/instances

A TrakHound Instance is the ASP.NET Core and Blazor host process. It loads installed Packages, exposes their HTTP endpoints, routes data requests to Services, and serves the admin UI used to configure everything running on it.

Diagram: An Instance serves Apps, APIs, the System API, the MCP Server, the API Catalog, and the admin UI on its HTTP port. It runs your modules: Apps, APIs, Functions, Workers, Services, and Identity providers. It keeps its configuration, Packages, Volumes, and logs in folders, and runs as a Windows Service, an IIS Application, or a Linux systemd service.

## Installing an Instance

Install an Instance on Windows as a Windows Service or into IIS, or on Linux as a systemd service, with the admin account created during setup. See [Installation](https://www.trakhound.com/docs/trakhound-framework/installation) for requirements, each hosting type, the admin account, HTTPS with a reverse proxy, silent installs, upgrading, and troubleshooting.

## Running an Instance

Run the Instance with an optional configuration profile ID and options:

```
TrakHound.Instance [configurationProfileId] --configurationPath <path> --packagePath <path> --volumePath <path> --deploymentPath <path>
```

| Argument | Environment Variable | Default | Description |
| --- | --- | --- | --- |
| `configurationProfileId` | `TRAKHOUND_CONFIGURATION_PROFILE` | `default` | The configuration profile to load. Profiles let one Instance installation keep separate sets of configuration. |
| `--configurationPath` | `TRAKHOUND_CONFIGURATION_PATH` | `config` | The directory containing configuration profiles. The profile ID is appended (ex. `config/default`). |
| `--packagePath` | `TRAKHOUND_PACKAGE_PATH` | `packages` | The directory where Packages are installed. |
| `--volumePath` | `TRAKHOUND_VOLUME_PATH` | `volumes` | The directory where Volumes are stored. |
| `--deploymentPath` | `TRAKHOUND_DEPLOYMENT_PATH` | `deployments` | A folder, or a single `.thd` file, of [deployments to install when the Instance starts](https://www.trakhound.com/docs/trakhound-framework/configuration#startup-deployments). |

> Environment variables take priority over command line options. Default directories are relative to the Instance's installation directory.

## Configuration File

Instance settings are stored in `instance.config.yaml` in the configuration profile directory (ex. `config/default/instance.config.yaml`). Keys are camelCase. Most settings can also be changed in the admin UI under **Config > Settings**, which saves them to the same file. Restart the Instance to apply settings that need it. A value can reference a [Variable](https://www.trakhound.com/docs/trakhound-framework/volumes-and-variables#variables) or an environment variable (ex. `httpPort: ${port}` or `name: ${env:DEVICE_NAME}`), so one Deployment can set up many devices. The Instance ID is kept apart, in `instance.id` in the configuration folder, which Deployments and backups leave out.

```
name: Shop Floor Instance
description: Instance for the main plant
httpPort: 8472
adminHttpPort: 8473
adminHttpAddress: 127.0.0.1
adminInterfaceEnabled: true
adminAuthenticationEnabled: true
systemApiEnabled: true
mcpEnabled: false
```

| Key | Default | Description |
| --- | --- | --- |
| `instance.id` (a file) |  | Unique ID of the Instance. Kept out of `instance.config.yaml` so a Deployment never gives every device the same ID. |
| `name`, `description` |  | Display name and description. |
| `httpAddress`, `httpPort` | All addresses, `8472` | Address and port the Instance listens on (not under IIS). Use `127.0.0.1` for local access only, or behind a reverse proxy. |
| `adminHttpPort`, `adminHttpAddress` | `0` (off) | Serves the admin UI and System API on a separate port, so they can be firewalled apart from Apps and APIs (not under IIS or Docker). |
| `trustedProxies` |  | IP addresses (ex. `127.0.0.1`) or networks (ex. `10.0.0.0/8`) of your [reverse proxies](https://www.trakhound.com/docs/trakhound-framework/installation#reverse-proxy), whose `X-Forwarded-For` and `X-Forwarded-Proto` headers are used. Applied when saved. |
| `packageVerification` | `Warn` | Checks Packages against their manifest and signature: `Off`, `Warn`, `Require`, or `RequireApproval` (see [Signing and Verification](https://www.trakhound.com/docs/trakhound-framework/packages#verification)). Applied when the Instance is restarted. |
| `packageInventoryReportInterval` | `6` (hours) | How often the installed Packages are reported to [TrakHound PackageManager](https://www.trakhound.com/docs/trakhound-framework/packages#package-manager) sources when nothing has changed. `0` turns the heartbeat off. |
| `maxRequestBodySizeMb` | `256` | The largest request body accepted, in megabytes. Larger requests get `413 Payload Too Large`. `0` is no limit. |
| `systemApiUnprotectedRemoteAccess` | `false` | Allows other machines to use System Resources and Service operations that no security profile covers (see [Security](https://www.trakhound.com/docs/trakhound-framework/security#unprotected)). Only turn it on for a trusted network. |
| `rateLimits` | Off | [Rate Limits](https://www.trakhound.com/docs/trakhound-framework/security#rate-limits) for the APIs, System API, and MCP Tools. |
| `basePath` |  | Base path when the Instance is hosted under a sub-path. |
| `adminAllowedAddresses` | Every address | The client addresses or networks (ex. `10.0.0.25`, `192.168.1.0/24`) the admin UI is served to. The Instance's own computer is always allowed, and others get `404 Not Found`. Applied when saved. |
| `adminInterfaceEnabled` | `true` | Enables the admin UI. When off, `/_admin` returns 404. |
| `adminAuthenticationEnabled` | `true` | Requires signing in to the admin UI. |
| `adminDefaultTheme` | `Dark` | Default theme of the admin UI. |
| `systemApiEnabled` | `true` | Enables the Instance's System API, used by the admin UI's remote tools. |
| `mcpEnabled` | `false` | Serves the [MCP Server](https://www.trakhound.com/docs/trakhound-framework/mcp-server) at `/_mcp`. Needs the System API. |
| `appsHttpEnabled`, `apiHttpEnabled` | `true` | Serve Apps and APIs over HTTP. |
| `initializationPageEnabled` | `true` | Shows a startup page while the Instance starts. When off, clients get 503 until it is ready. |
| `initializationPagePath` | Built-in page | The folder of a [custom startup page](https://www.trakhound.com/docs/trakhound-framework/instances#initialization-page), relative to the configuration profile folder or absolute. Applied when saved. |
| `errorPageEnabled` | `true` | Shows the error page, with a Request ID to find the error in the logs. When off, returns a plain status code. Routes that aren't configured always get a plain status code. |
| `packageUpdateCheckInterval` | `6` (hours) | How often Package sources are checked for updates. `0` turns it off. Package sources are set on the **Packages > Sources** tab. |
| `directories` |  | Overrides for the `config`, `packages`, `logs`, `volumes`, `modules`, and `temp` directories. |

Log settings (provider, minimum level, retention, and archiving) are in `logs.config.yaml` in the same directory. Module configurations, Configuration Variables, and Deployments are covered in [Configuration & Deployments](https://www.trakhound.com/docs/trakhound-framework/configuration).

## Admin UI

Every Instance includes a browser-based admin UI at `/_admin`. With a separate Admin port, it is served only on that port. Each admin account's [roles](https://www.trakhound.com/docs/trakhound-framework/security#admin-accounts) decide which areas it can view and change, and the **?** icon on each page opens its page in these docs.

- **Explorer** - Run API endpoints, preview App pages, run Functions with Jobs, schedule them on the Schedule Board, start and stop Workers, and browse Service data. The Apps and App Connections pages manage open App pages (see [Apps](https://www.trakhound.com/docs/trakhound-framework/apps#updates))
- **Instance** - **Overview**, **Information** (admin sign-in, Admin port and System API status, and why the previous run stopped if it didn't shut down cleanly), **Monitor**, [Boots](https://www.trakhound.com/docs/trakhound-framework/instances#boots), and **Log**
- **Monitor** - The Instance's CPU and memory, and **CPU by Module**: the CPU used by each Worker, Function, API, App, and the admin UI, with a 10 minute chart
- **Diagnostics** - Health checks, loaded modules and their errors, a [Logs](https://www.trakhound.com/docs/trakhound-framework/instances#logs) overview, live metrics for APIs, Apps, HTTP, Functions, Services, Workers, Streams (WebSocket and Server-Sent Events), MCP, and Buffers, and recent HTTP Requests, API Requests (with the error and Request ID of failed ones), and API Streams (including Streams opened inside the Instance, with a Close Stream button)
- **Packages** - Browse, install, upload, update, verify, and revert Packages from configured sources, and remove Packages no configuration uses
- **Config** - Everything a Deployment carries: APIs, Apps, Functions, Workers, Services, Routers, Identity providers, [Groups](https://www.trakhound.com/docs/trakhound-framework/configuration#groups), **Access** ([security profiles](https://www.trakhound.com/docs/trakhound-framework/security), [Zones](https://www.trakhound.com/docs/trakhound-framework/zones), and the Zone Map), and **Instance** ([Configuration Variables](https://www.trakhound.com/docs/trakhound-framework/configuration#variables) and Settings)
- **Settings** (under Config) - General, Interfaces (ports, Admin port, Admin Allowed Addresses, Trusted Proxies, Max Request Size, System API, Unprotected Remote Access, MCP Server), Rate Limits, Logs, Notifications, Metrics, and Health settings
- **Deploy** - Create and install [Deployments](https://www.trakhound.com/docs/trakhound-framework/configuration#deployments), restore backups, and set up other Instances in [Workspaces](https://www.trakhound.com/docs/trakhound-framework/configuration#workspaces)
- **Security** - Identity providers, Users, API keys, [Admin Accounts and Roles](https://www.trakhound.com/docs/trakhound-framework/security#admin-accounts), What is Public?, Access Check, [Trusted Publishers](https://www.trakhound.com/docs/trakhound-framework/packages#verification), and the [Audit Log](https://www.trakhound.com/docs/trakhound-framework/security#audit) (see [Security](https://www.trakhound.com/docs/trakhound-framework/security))
- **Licenses** - Copy the Device ID used to request a license, add or import licenses with a Description, and see what each is assigned to. Licenses are checked on the server, without contacting the publisher (see the [Licensing Guide](https://www.trakhound.com/docs/licensing))

> The admin UI can't create the first admin account. If none exists, the sign-in page says how to create one on the Instance's machine (see [Admin Account](https://www.trakhound.com/docs/trakhound-framework/installation#admin-account)). The help links only open pages on trakhound.com; the admin UI never requests anything from it, so an Instance without internet access works the same.

## Health Checks

Two public endpoints suit load balancers and monitoring:

| URL | Returns |
| --- | --- |
| `/_health` | 200 when Healthy or Degraded, 503 when Unhealthy, with `{"status": ...}` |
| `/_health/live` | 200 while the process is running |

**Explorer > Diagnostics > Health** shows each check (Services, Resources, Disk, Packages, and Workers). Mark checks as Critical or Ignore under **Settings > Health**.

## CPU by Module

**Instance > Monitor** shows the CPU used by each Worker, Function, API, and App and by the admin UI, so you can see which module is using the server. API and App Metrics also show CPU per API, Endpoint, and App, and `GET /_instances/cpu` returns the same breakdown. It is measured when **Settings > Metrics > Measure CPU Usage** is on.

- A module's CPU includes the Services it calls. When one module calls another (ex. a Worker calls an API), the time is counted to the module that was called.
- An App's CPU is the work its pages do in the browser's connection to the Instance (events, rendering, and JavaScript calls).
- **Unattributed** is process CPU no module accounts for: the HTTP server, Services' background work, and the .NET Garbage Collector.

## Logs

The **Log** tabs of the Instance, an API, an Endpoint, and a Worker, and **Explorer > Diagnostics > Logs**, all work the same way:

- **Live** shows new lines as they're written, from when the tab opens. **Unsubscribe** pauses it.
- **History** shows the lines kept in Log History, newest first, filtered by **Minimum Level** and **Range** (the last hour to the last 30 days).

**Diagnostics > Logs** lists the loggers, grouped by Package (ex. `api/TrakHound.Functions.Api`) or system logger, with the most Errors and Warnings over the last hour, 24 hours, or 7 days first. Click **Errors** or **Warnings** to show only the loggers with them, and click a logger to open its History. The top of the page says what Log History keeps (levels, days, and size) and links to **Settings > Logs**.

## Boot History

The Instance's **Boots** tab lists the last 100 runs of the Instance process, newest first, with how each ended, when it started, its boot time (from the process starting until the HTTP server and the Runtime are running), the warnings and errors logged while it started, and its uptime. Click a run to see each startup step with its duration, the step that failed and its exception, and each Runtime start and restart.

| Status | Meaning |
| --- | --- |
| **Starting** | The process is starting |
| **Running** | The process started and is still running (marked **Current** for this process) |
| **Stopped** | The process shut down normally. **Ended** shows why (ex. a Windows Service stop or Ctrl+C) |
| **Failed** | The process couldn't start (ex. the HTTP port is in use) |
| **Crashed** | An unhandled exception ended the process |
| **Unclean** | The process ended without shutting down (ex. it was killed, or the power was lost). The next run fills in the reason |

After an unclean shutdown, the Instance shows a **Previous Run did not Shut Down Cleanly** notification. The **Information** tab's **Last Shutdown** shows the reason, and **Shutdown Details** shows the exception and, on Windows, the Event Log entries about the stopped process, which explain crashes the Instance can't log itself.

**JSON** downloads everything recorded for each Boot (or one Boot, ex. for a support request), and **CSV** one summary row per Boot for a spreadsheet. Boots are kept in `boots.json` in the configuration profile folder, so they're recorded even when Log History is off, and Deployments and backups leave the file out. The System API serves them at `/_instances/boots` and `/_instances/boots/{bootId}` (the `system:instance` resource), and the [MCP Server](https://www.trakhound.com/docs/trakhound-framework/mcp-server) has `instance_boots` and `instance_boot` Tools.

## Custom Initialization Page

While the Instance starts, restarts, or is stopped, browsers that request an App are sent to the Initialization Page (`/_init`), which reloads every 5 seconds until the Instance is running. Replace it with your own page, such as a branded loading screen for kiosk displays:

1. Create a folder with an `index.html`, ex. `config/default/init`, with its images and stylesheets in the same folder.
2. Set **Settings > Interfaces > Custom Initialization Page** (or `initializationPagePath`) to the folder, ex. `init`.
3. Click **Preview the Initialization Page** under the setting to check it while the Instance is running.

The page is plain HTML (the Instance's stylesheets and Blazor aren't loaded), and the Instance reloads it, so it doesn't need a script. These tokens are replaced in `index.html`:

| Token | Value |
| --- | --- |
| `{{assets}}` | The path of the folder's files, ex. `<img src="{{assets}}/logo.png" />` |
| `{{status}}` | `Starting`, `Stopping`, `Stopped`, or `Error` (the Instance didn't start) |
| `{{title}}`, `{{description}}` | The built-in page's text for the status |
| `{{route}}` | The page the browser will load when the Instance is running |
| `{{timestamp}}`, `{{retrySeconds}}` | When the page was loaded, and how often it reloads |

> The folder's other files are served at `/_init/assets/...` without signing in, so don't put anything private there. If `index.html` is missing or can't be read, the built-in page is shown and the setting shows a warning.
