Instances

Run and configure the host application: settings, the admin UI, health checks, and CPU by Module.
Framework Docs Menu

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
Serves on its HTTP port (default 8472)
Your Apps Your APIs /_services, /_functions, ... (System API) /_mcp /_developer, /llms.txt /_admin /_health
Runs your modules
AppsBlazor pages
APIsHTTP endpoints and streams
FunctionsOn demand or scheduled
WorkersBackground processes
ServicesData in databases and brokers
IdentitySign-in and API keys
Keeps its files in
config/<profile>instance.config.yaml, module configurations, Variables, Routers, and Zones
packagesInstalled Packages, every version side by side
volumesEach module's files
logsLog history, also in Diagnostics > Logs
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 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>
ArgumentEnvironment VariableDefaultDescription
configurationProfileIdTRAKHOUND_CONFIGURATION_PROFILEdefaultThe configuration profile to load. Profiles let one Instance installation keep separate sets of configuration.
--configurationPathTRAKHOUND_CONFIGURATION_PATHconfigThe directory containing configuration profiles. The profile ID is appended (ex. config/default).
--packagePathTRAKHOUND_PACKAGE_PATHpackagesThe directory where Packages are installed.
--volumePathTRAKHOUND_VOLUME_PATHvolumesThe directory where Volumes are stored.
--deploymentPathTRAKHOUND_DEPLOYMENT_PATHdeploymentsA folder, or a single .thd file, of deployments to install when the Instance starts.
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 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
KeyDefaultDescription
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, descriptionDisplay name and description.
httpAddress, httpPortAll addresses, 8472Address and port the Instance listens on (not under IIS). Use 127.0.0.1 for local access only, or behind a reverse proxy.
adminHttpPort, adminHttpAddress0 (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).
trustedProxiesIP 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.
packageVerificationWarnChecks Packages against their manifest and signature: Off, Warn, Require, or RequireApproval (see Signing and Verification). Applied when the Instance is restarted.
packageInventoryReportInterval6 (hours)How often the installed Packages are reported to TrakHound PackageManager sources when nothing has changed. 0 turns the heartbeat off.
maxRequestBodySizeMb256The largest request body accepted, in megabytes. Larger requests get 413 Payload Too Large. 0 is no limit.
systemApiUnprotectedRemoteAccessfalseAllows other machines to use System Resources and Service operations that no security profile covers (see Security). Only turn it on for a trusted network.
rateLimitsOffRate Limits for the APIs, System API, and MCP Tools.
basePathBase path when the Instance is hosted under a sub-path.
adminAllowedAddressesEvery addressThe 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.
adminInterfaceEnabledtrueEnables the admin UI. When off, /_admin returns 404.
adminAuthenticationEnabledtrueRequires signing in to the admin UI.
adminDefaultThemeDarkDefault theme of the admin UI.
systemApiEnabledtrueEnables the Instance's System API, used by the admin UI's remote tools.
mcpEnabledfalseServes the MCP Server at /_mcp. Needs the System API.
appsHttpEnabled, apiHttpEnabledtrueServe Apps and APIs over HTTP.
initializationPageEnabledtrueShows a startup page while the Instance starts. When off, clients get 503 until it is ready.
initializationPagePathBuilt-in pageThe folder of a custom startup page, relative to the configuration profile folder or absolute. Applied when saved.
errorPageEnabledtrueShows 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.
packageUpdateCheckInterval6 (hours)How often Package sources are checked for updates. 0 turns it off. Package sources are set on the Packages > Sources tab.
directoriesOverrides 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)
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). 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:

URLReturns
/_health200 when Healthy or Degraded, 503 when Unhealthy, with {"status": ...}
/_health/live200 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.

StatusMeaning
StartingThe process is starting
RunningThe process started and is still running (marked Current for this process)
StoppedThe process shut down normally. Ended shows why (ex. a Windows Service stop or Ctrl+C)
FailedThe process couldn't start (ex. the HTTP port is in use)
CrashedAn unhandled exception ended the process
UncleanThe 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:

  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:

TokenValue
{{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.