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.
instance.config.yaml, module configurations, Variables, Routers, and ZonesInstalling 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 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. |
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 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, 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). Applied when the Instance is restarted. |
packageInventoryReportInterval | 6 (hours) | How often the installed Packages are reported to TrakHound PackageManager 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). Only turn it on for a trusted network. |
rateLimits | Off | 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 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, 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.
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 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)
- 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, 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 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, Access (security profiles, Zones, and the Zone Map), and Instance (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, restore backups, and set up other Instances in Workspaces
- Security - Identity providers, Users, API keys, Admin Accounts and Roles, What is Public?, Access Check, Trusted Publishers, and the Audit Log (see 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)
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 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:
- Create a folder with an
index.html, ex.config/default/init, with its images and stylesheets in the same folder. - Set Settings > Interfaces > Custom Initialization Page (or
initializationPagePath) to the folder, ex.init. - 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 |
/_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.