A configuration links a Package to the settings it runs with: its route, Volume, Router, and parameters. One Package can run under several configurations, each with its own settings. Configurations are created in the admin UI under Config, which saves them as YAML files in the Instance's configuration profile.
MyCompany.Machines.Api
The code. Installed, but not running until a configuration uses it
/line1/machines · Volume line1 · Router default · Version *
/line2/machines · Volume line2 · Router default · Version 1.3.2
sqlServer = sql01.mycompany.local · set once for the whole profile, and read by both configurationsConfiguration Files
Each configuration is stored in the profile's configuration directory, grouped by category:
config/
default/
instance.config.yaml Instance settings (see Instances)
variables.config.yaml Configuration Variables
api/ One file per configured API
app/ One file per configured App
function/ One file per configured Function
worker/ One file per configured Worker
service/ One file per configured Service
router/ One file per Router
identity/ One file per Identity provider
group/ One file per Group
zone/ One file per Zone
For example, an API configuration:
id: example-api
name: Example API
route: example/api
volumeId: example
routerId: default
packageId: TrakHound.Example.Api
packageVersion: "*"
httpEnabled: true
parameters:
directory: ${dataPath}/files
| Key | Applies To | Description |
|---|---|---|
id, name, description | All | Identify the configuration. |
packageId, packageVersion | All | The Package to load. A version of * uses the newest stable installed version, and patterns such as 1.2.* also work (see Versions). |
parameters | All | Name and value pairs read by the module. Values can reference Configuration Variables. |
volumeId | All | The Volume provided to the module. Empty uses the configuration id. A Package's .defaultVolumeId fills in an empty value when a version the configuration runs is installed; the module then uses that Volume, and its files aren't moved. |
routerId | All but Services | The Router used for data requests. Empty uses the Router of the configuration's Group, then default. |
groupId | API, App, Function, Worker | The Group the configuration is in. |
route | API, App | The route the API or App is served at. Must be unique. |
httpEnabled | API | false serves the API only inside the Instance (to other modules). |
mcpTools, mcpReadOnly, mcpInclude, mcpExclude | API | Which endpoints are served as MCP Tools. |
functionId | Function | The ID used to run the Function. |
Adding a Configuration
- In the admin UI, open Config, choose the category (for example Api), and click Add.
- Choose a Package From Source or Installed. Tick Use Latest Version to follow updates.
- Fill in General (Name, Route, Function ID, Volume, Router, and so on), the Settings provided by the Package, and any Parameters.
- Click Add. Each list shows whether a configuration is Running, Not loaded, or Package missing.
".configurationParameters": "host,port,useSsl") so they appear as fields in the configuration form.
Secret Parameters
Parameters whose names contain password, token, or secret, or end in key (but not name or id),
are encrypted in the configuration file when it is saved, and are hidden in the admin UI. Modules read them decrypted with Configuration.GetParameter(name).
Configuration Variables
Configuration Variables are values shared by every configuration in a profile, such as a data directory or a server name that many modules use.
Reference one from any parameter value as ${name}, or an environment variable of the Instance process as ${env:NAME}.
$${name} is the literal text ${name}.
# variables.config.yaml
dataPath: D:\TrakHound\Data
sqlServer: sql01.mycompany.local
# A Function configuration
parameters:
directory: ${dataPath}/reports
server: ${sqlServer}
apiKey: ${env:REPORTS_API_KEY}
- Edit Variables in the admin UI under Config > Variables, which shows how many configurations use each one and lists references to Variables that are not defined.
- Variables named like a secret are encrypted when saved and are never shown again. Type a new value to replace one.
- Variables are read when the Instance starts. After saving, click Restart Instance to apply them.
- A reference to a Variable that is not defined is left as it is, and a warning is logged.
In a module, GetParameter() returns values with references replaced (read parameters through it rather than the Parameters dictionary).
APIs, Apps, Functions, and Workers can also read a Variable by name:
var dataPath = GetConfigurationVariable("dataPath"); // null if it isn't defined
Groups
A Group organizes APIs, Apps, Functions, and Workers, such as the modules of one line, and sets the Router of those that don't name their own.
Groups never restrict anything: a Zone can list a Group (group:{id}) to restrict every module in it.
- Under Config > Groups, click Add Group and give it an ID, which modules and Zones refer to it by.
- On its page, set a Name, Description, and Router.
- Add modules with Add Module on the Group's page, or pick the Group on a module's configuration page.
Explorer lists a Group's modules in a folder for the Group, and filtering by its name shows them. The Group's page lists the Zones that refer to it, and removing a Group takes its modules out of it.
th packages install <packageId> --configure --group <id> puts the configurations it adds in a Group.
Deployments
A Deployment copies an Instance's configurations and Packages, and optionally its Package data (Volumes and Package Variables), to other Instances. Create and install Deployments in the admin UI under Deploy,
or with the CLI (th deployments).
| Section | What you can do |
|---|---|
| Create | Choose Full or Incremental, a Version and Description, the configuration profile, the Configurations to include (all, or only some categories such as Api, Functions, Services, or the profile's Instance Settings), which Packages to include (all installed, only those used by configurations, or None), which Volumes and Package Variables to include (none by default), and whether to Include Secrets (the admin accounts, Users, API keys, and secret values; without them the target keeps its own). Recent Deployments can be downloaded again. |
| Install | Drop a Deployment file, review the changes (including the licenses a Deployment for this device adds), optionally back up first, then click Stop Instance and Install. |
| Backups | Restore or delete a backup made before an install. |
| Workspaces | Create, open, export, and delete Workspaces, which hold the configuration for other Instances. |
- Copy only settings - Include only the configuration categories you want and choose None for Packages. Installing replaces only the included categories, and the Package versions on the target are not changed.
- Variables and Zones - A Deployment includes the profile's Configuration Variables (
variables.config.yaml, part of the Instance Settings category, so leaving out Instance Settings leaves them out too), and can include Zones. - Secrets - A Deployment made with Include Secrets carries the secret values. Store and send the file securely.
- Package data - Include the Volumes (folders in the
volumesfolder, ex. a configuration's ID) and Package Variables (one collection per configuration ID) that hold settings your Packages keep:- Installing adds or replaces the Deployment's Volume files. Other files in the target's Volumes are kept, and nothing is deleted.
- Each Package Variables collection replaces the target's collection with the same ID.
- Incremental Deployments include only the Volume files and collections changed since the last Deployment, and backups include what the install replaces.
- They're copied as they are, and Include Secrets doesn't apply to them, so don't include Volumes that hold passwords or keys unless you would include secrets.
Jobs and Scheduled Tasks are copied between Instances separately, with Export and Import on the Schedule Board.
Installing a Deployment at Startup
When it starts, before it reads any configuration, the Instance installs the deployment files (.thd) in its deployments folder.
Use this to set up a new Instance with a known set of configurations and Packages: select a file on the Windows installer's Deployment page
(or pass /DEPLOYMENT=), pass --deployment to the Linux install.sh, or copy a file into the folder and restart the Instance.
- Files are installed in name order (ex.
01-base.thdbefore02-site.thd), each with a backup first. If an install fails, the backup is restored and the Instance starts with its previous configuration. - Each file is installed only once, so passing the same file again on an upgrade doesn't overwrite changes made since. Installed files are moved to
deployments/installed(ordeployments/failed). - Deploy > Install > Installed at Startup lists the results, and a notification shows each one.
- Set
TRAKHOUND_DEPLOYMENT_PATH(or--deploymentPath) to read deployments from another folder, or from a single file such as a read-only Docker mount.
Workspaces
A Workspace holds the configurations, Variables, Zones, and Instance Settings for another Instance, so you can set it up without changing this one, ex. a device with no screen. Create one on Deploy > Workspaces, then open its Configuration, Zones, or Settings: they're the same admin pages, with a banner that shows which Workspace you're editing.
- Nothing in a Workspace runs on this Instance. Saving a configuration doesn't install its Package, and Workspaces aren't part of this Instance's Deployments or backups.
- Export creates a Deployment that replaces the target profile's APIs, Apps, Functions, Workers, Services, Identity providers, Routers, Groups, and Zones with the Workspace's, and carries its Variables and Instance Settings. Security profiles on the target are kept.
- The Package versions it uses are copied from this Instance, or downloaded from the Package source if they aren't installed here.
- For settings that differ on each device, set them to a Variable on the Settings page (ex. the port as
${port}).
Licenses and devices - Licenses are issued for one device, so a Deployment only carries them when it's for one device:
- Add the License Files you received to the Workspace's Licenses, and enter the device's ID in Target Device ID when you export. The Deployment then includes that device's licenses and can only be installed on that device.
- List several devices on the Workspace's Devices, each with a label, its Device ID, and the Variable values that differ on it (ex. a PLC address). Export then creates a Deployment for each device, downloaded together in one
.zip. - On a device without the admin UI,
TrakHound.Instance device-idshows its Device ID (see Installation). - Installing adds the licenses to the device's own, and a Deployment never sets a device's ID.