Controller Configuration

Last updated: June 1, 2026Latest Frontend Version: 2.16.20

Configuration file location

Linux
Windows

/etc/ticrypt/controller.toml

C:\Program Files\Tera Insights\tiCrypt VM Controller\controller.toml

The controller.toml configuration is a TOML file that defines VM Controller behavior. It is set once during image preparation and applies to every VM that boots from that image. The configuration file is required on both Linux and Windows images. Most parameters apply to both platforms; platform-specific parameters are noted in their descriptions.

Value Types

Type	Example	Description
String	`"an example"`	String value
Int	`42`	Whole number
Bool	`true`, `false`	Boolean
Port	`22`	Number between 0 and 65535
Range	`"5000-5010"`	Range of ports (as a string)
Duration	`"1m"`, `"2h"`, `"3d"`	Duration with unit of measure
ArrPort	`[5000, 5002, 5005]`	Array of port values
ArrString	`["a", "b", "c"]`	Array of string values

Global Settings

These options are specified at the top level of the file, outside any section.

Parameter	Type	Default	Description
`FIPSModeOff`	Bool	`false`	Disable FIPS mode. Only set to `true` if your environment does not require FIPS compliance
`ControllerSubvariant`	String	`""`	Download an alternative controller binary. The VM Installer fetches from `http://vmc.ticrypt/<arch>/<os>/<variant>/<subvariant>`. Falls back to the default if the subvariant is unavailable
`ConfigPrefix`	String	`""`	Load an alternative configuration file named `<prefix>-controller.toml` from the same directory. The VM Installer falls back to the default if unavailable

`[debug]`

Parameter	Type	Default	Description
`logLevel`	String	`"info"`	Log verbosity. Values: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`
`enableManagerSudo`	Bool	`false`	Allow VM managers to execute root/Administrator commands

`[terminal]`

Controls the web-based terminal available in the tiCrypt frontend. The terminal provides direct OS interaction without requiring user login through SSH.

Parameter	Type	Default	Description
`enabled`	Bool	`true`	Enable or disable the terminal service
`command`	String	Platform-specific	Shell command to launch. Linux: `"/bin/bash"`, Windows: `"powershell.exe"`
`scrollback`	Int	`10000`	Number of scrollback history lines
`maxScrollback`	Int	`100000`	Maximum scrollback buffer size

`[tunnel]`

Controls TLS-tunneled TCP connections to applications running inside the VM. Since all other network paths are blocked by the tiCrypt infrastructure, tunneling is the only way for users to reach applications.

Parameter	Type	Default	Description
`enabled`	Bool	`true`	Enable or disable the tunneling service
`serverPort`	Port	`22`	TCP port for the tunneling service
`allowedPorts`	Port, Range, or ArrPort	`[]`	Ports that can be forwarded. Add entries for every application users need to reach
`addGroups`	ArrString	`[]`	System groups to add tunneling users to (e.g., `["Remote Desktop Users"]` on Windows)
`tunlsLogLevel`	Int	`1`	Tunnel log level: 0 = None, 1 = Errors, 2 = Warnings, 3 = Info, 4 = Debug
`idleTimeout`	Duration	`"15m"`	Kill tunnels after this period of inactivity. Minimum non-zero value is 1 second

SFTP

When enabled, SFTP allows users to transfer files from their local machine into the VM while running tiCrypt. The connection is one-way only: users can upload files into the VM but cannot use SFTP to download or read files from it. The VM Controller runs a controlled SSH daemon that permits only SFTP uploads, with no console access or file reads.

Parameter	Type	Default	Description
`sftpEnabled`	Bool	`false`	Enable SFTP support
`sftpPort`	Port	`2022`	Local port for the SFTP SSH daemon. Automatically added to allowed tunnel ports
`sshDirPath`	String	`""`	Path to directory containing `sshd` and `ssh-keygen` executables. If empty, the controller checks the assets archive (`bin/ssh/`) then the system PATH

note

SFTP requires OpenSSH installed on the image with its service disabled so it does not bind port 22 at boot. See the Linux or Windows image creation guides for setup steps.

`[tunnel.services]`

Optional names for forwarded ports. These names appear in the connection instructions shown to users in the tiCrypt frontend.

[tunnel.services]
vnc = 5901
xpra = 14500
my_app = 8080

Naming a port here does not allow it for tunneling. You must also add the port to allowedPorts.

`[tunnel.cert]`

Options for the self-signed TLS certificate generated by the tunneling service.

Parameter	Type	Default	Description
`country`	String	`""`	Two-letter country code
`organization`	String	`"unspecified"`	Organization name

`[stats]`

Parameter	Type	Default	Description
`systemInterval`	Duration	`"1s"`	How often to poll system statistics
`logErrors`	Bool	`false`	Log statistics collection errors. Disabled by default because timeouts are common on Windows under heavy CPU load

`[users]`

Parameter	Type	Default	Description
`dontChangeAdminPassword`	Bool	`false`	If `true`, skip changing the admin password at startup
`managersAsAdmin`	Bool	`false`	Automatically grant VM managers administrator privileges
`createDirs`	ArrString	`[]`	Directories to create in each user's home on their encrypted drive
`createHiddenDirs`	ArrString	`[]`	Hidden directories to create in each user's home
`passwordLength`	Int	`32`	Length of the random password generated for users
`userProfileLinkType`	String	`"junction"`	Windows only. How user profile directories are linked. Values: `"junction"`, `"softlink"`

`[commands]`

Run scripts at specific stages of the VM lifecycle: application environment setup, permission adjustments, and user-specific resource configuration.

Structure

Commands are organized by privilege level and execution frequency:

[commands.rootCommands.runOnlyOnceCommands]    # Root, first occurrence only
[commands.rootCommands.runEveryTimeCommands]    # Root, every occurrence
[commands.userCommands.runOnlyOnceCommands]     # User, first occurrence only
[commands.userCommands.runEveryTimeCommands]    # User, every occurrence

"Run only once" commands execute on the first occurrence of the event. If the command fails, it retries on subsequent occurrences until it succeeds.

Events

Event	Description	Available Macros
`on_login`	User logs in	`@:user:`
`on_homeDriveAttached`	Home drive is attached
`on_driveAttached`	Any drive is attached	`@:driveName:`, `@:driveSlot:`, `@:driveType:`
`on_vpnConnected`	VPN connection established

When a home drive is attached, both on_homeDriveAttached and on_driveAttached fire in that order.

Macros

Use @:macroName: in command strings. The controller replaces the macro with the actual value at runtime. The @:user: macro can appear multiple times in a single command.

Async Mode

Append -async to the event name to run commands asynchronously:

[commands.rootCommands.runEveryTimeCommands]
on_login = {setXdgRuntime = "install -o @:user: -m 700 -d /run/user/$(id -u @:user:)"}
on_driveAttached-async = {setEnv = "export DRIVE=@:driveName:"}

Syntax

event_name = {action_name = "command", another_action = "command with args"}

note

User-context events like on_login cannot be used in rootCommands sections that require user information, unless you use the @:user: macro in a root command.

`[fileSystem]`

Parameter	Type	Default	Description
`secureTransfer`	Bool	`false`	Enable the secure file transfer system
`allowedTransferProtocols`	ArrString	`[]`	List of permitted transfer protocols

Annotated Example

Below is a complete controller.toml broken into sections. Each section includes a table explaining every parameter, followed by the corresponding TOML.

Global Settings

Parameter	Default	Explanation
`FIPSModeOff`	`false`	Controls whether FIPS 140-2 mode is active. Leave as `false` for environments that require federal compliance. Set to `true` only if FIPS is not a requirement
`ControllerSubvariant`	`""`	Selects an alternative controller binary. The VM Installer appends this value to its download path. Useful for testing or specialized deployments. Empty means use the standard controller
`ConfigPrefix`	`""`	Loads a different config file named `<prefix>-controller.toml`. Allows a single image to support multiple configurations. Empty means use the default `controller.toml`

# FIPSModeOff = false
# ControllerSubvariant = ""
# ConfigPrefix = ""

`[debug]`

Parameter	Default	Explanation
`logLevel`	`"info"`	Controls how verbose the VM Controller logs are. Use `"debug"` or `"trace"` when diagnosing issues; use `"warn"` or `"error"` in production to reduce noise
`enableManagerSudo`	`false`	When `true`, users with the Manager role can run root (Linux) or Administrator (Windows) commands through the tiCrypt terminal. Keep disabled unless managers need elevated access for administration

[debug]
# logLevel = "info"
# enableManagerSudo = false

`[terminal]`

Parameter	Default	Explanation
`enabled`	`true`	Enables the web-based terminal in the tiCrypt frontend. Disable if users should only access the VM through tunneled applications (e.g., RDP)
`command`	Platform-specific	The shell launched when a user opens a terminal session. Defaults to `/bin/bash` on Linux, `powershell.exe` on Windows. Change to a custom shell or a wrapper script if needed
`scrollback`	`10000`	Number of lines of terminal history the user can scroll back through. Higher values use more memory per session
`maxScrollback`	`100000`	Hard upper limit on the scrollback buffer. Prevents runaway memory usage from long-running terminal sessions

[terminal]
enabled = true
# command = "/bin/bash"       # Linux
# command = "powershell.exe"  # Windows
# scrollback = 10000
# maxScrollback = 100000

`[tunnel]`

Parameter	Default	Explanation
`enabled`	`true`	Enables TLS-tunneled TCP connections to applications inside the VM. Since all other network paths are blocked, this is the only way to reach applications like RDP, VNC, or web servers
`serverPort`	`22`	The TCP port the tunneling service binds to. Must be `22` because it is the only port the tiCrypt network infrastructure allows through. Do not change unless explicitly instructed
`allowedPorts`	`[]`	Ports that users can forward through the tunnel. Add every application port users need to access. Accepts a single port (`5901`), a range (`"5901-5905"`), or an array (`[14500, 5901]`)
`addGroups`	`[]`	System groups that tunneling users are automatically added to. For Windows images with RDP, set to `["Remote Desktop Users"]` so users can connect
`tunlsLogLevel`	`1`	Verbosity of tunnel-specific log messages. 0 = None, 1 = Errors only, 2 = Warnings, 3 = Info, 4 = Debug. Increase when diagnosing tunnel connection problems
`idleTimeout`	`"15m"`	Tunnels with no active forwarded connections are terminated after this duration. Set to `"0"` to disable idle cleanup. Minimum non-zero value is `"1s"`
`sftpEnabled`	`false`	Allows users to SFTP files from their local machine into the VM. One-way only: uploads are permitted, downloads and file reads are not. Requires OpenSSH installed but its service disabled (see Linux/Windows creation guides)
`sftpPort`	`2022`	Local port for the SFTP SSH daemon. Automatically added to the allowed tunnel ports. Change only if port 2022 conflicts with another service
`sshDirPath`	`""`	Path to the directory containing `sshd` and `ssh-keygen` executables. Leave empty to auto-detect from the assets archive or system PATH

[tunnel]
enabled = true
# serverPort = 22
# allowedPorts = []
# allowedPorts = 5901
# allowedPorts = "5901-5905"
# allowedPorts = [14500, 5901]
# tunlsLogLevel = 1
# addGroups = []
# addGroups = ["Remote Desktop Users"]  # Windows RDP
# idleTimeout = "15m"
sftpEnabled = true
sftpPort = 2022
# sshDirPath = ""

`[tunnel.services]`

Parameter	Default	Explanation
`<name>`	(none)	Maps a human-readable name to a port number. These names appear in the connection instructions shown to users in the tiCrypt frontend. Naming a port does not allow it for tunneling; it must also appear in `allowedPorts`

[tunnel.services]
# vnc = 5901
# xpra = 14500

`[tunnel.cert]`

Parameter	Default	Explanation
`country`	`""`	Two-letter country code embedded in the self-signed TLS certificate the tunneling service generates. Optional but recommended for organizational compliance
`organization`	`"unspecified"`	Organization name in the certificate. Set to your organization's name for audit clarity

[tunnel.cert]
# country = "US"
# organization = "unspecified"

`[stats]`

Parameter	Default	Explanation
`systemInterval`	`"1s"`	How frequently the controller polls CPU, memory, and disk statistics. Longer intervals reduce overhead on resource-constrained VMs
`logErrors`	`false`	Whether to log errors from stats collection. Disabled by default because Windows VMs under heavy CPU load frequently time out when querying CPU information, which generates noisy logs

[stats]
# systemInterval = "1s"
# logErrors = false

`[users]`

Parameter	Default	Explanation
`dontChangeAdminPassword`	`false`	When `false`, the controller randomizes the admin password at startup for security. Set to `true` only if you need a known admin password for debugging
`managersAsAdmin`	`false`	Automatically grants Administrator (Windows) or root-equivalent (Linux) privileges to users with the Manager role. Use with caution
`createDirs`	`[]`	Directories to create in each user's home folder on their encrypted drive. Useful for setting up expected folder structures (e.g., `["Documents", "Projects"]`)
`createHiddenDirs`	`[]`	Same as `createDirs` but for hidden directories (prefixed with `.` on Linux)
`passwordLength`	`32`	Length of the random password generated for each user account. Higher values increase security but have no user-facing impact since passwords are managed automatically
`userProfileLinkType`	`"junction"`	Windows only. Controls how user profile directories are linked to the encrypted drive. `"junction"` is the default and works in most cases. Use `"softlink"` if junctions cause issues with specific applications

[users]
# dontChangeAdminPassword = false
# managersAsAdmin = false
# createDirs = []
# createHiddenDirs = []
# passwordLength = 32
# userProfileLinkType = "junction"  # Windows only

`[commands]`

Sub-section	Explanation
`[commands.rootCommands.runOnlyOnceCommands]`	Commands executed as root/Administrator on the first occurrence of each event. If a command fails, it retries on subsequent occurrences until it succeeds
`[commands.rootCommands.runEveryTimeCommands]`	Commands executed as root/Administrator on every occurrence of each event
`[commands.userCommands.runOnlyOnceCommands]`	Commands executed as the logged-in user on the first occurrence. Same retry behavior as root run-once commands
`[commands.userCommands.runEveryTimeCommands]`	Commands executed as the logged-in user on every occurrence

Syntax: event_name = {action_name = "command", another = "command with @:user: macro"}

Async: Append -async to the event name (e.g., on_driveAttached-async) to run commands without blocking the boot process.

[commands]
[commands.rootCommands]
[commands.rootCommands.runOnlyOnceCommands]
# on_login = {createDir = "mkdir -p /opt/app"}

[commands.rootCommands.runEveryTimeCommands]
# on_login = {setXdgRuntime = "install -o @:user: -m 700 -d /run/user/$(id -u @:user:)"}
# on_driveAttached-async = {logDrive = "echo attached @:driveName: to @:driveSlot:"}

[commands.userCommands]
[commands.userCommands.runOnlyOnceCommands]
# on_login = {initConfig = "cp /etc/skel/.bashrc ~/"}

[commands.userCommands.runEveryTimeCommands]
# on_login = {setEnv = "export APP_HOME=/opt/app"}

`[fileSystem]`

Parameter	Default	Explanation
`secureTransfer`	`false`	Enables the secure file transfer system, which provides an audited mechanism for moving data in and out of the VM beyond SFTP
`allowedTransferProtocols`	`[]`	Restricts which transfer protocols are permitted when secure transfer is enabled. Leave empty to allow all supported protocols

# [fileSystem]
# secureTransfer = false
# allowedTransferProtocols = []

Value Types​

Global Settings​

[debug]​

[terminal]​

[tunnel]​

SFTP​

[tunnel.services]​

[tunnel.cert]​

[stats]​

[users]​

[commands]​

Structure​

Events​

Macros​

Async Mode​

Syntax​

[fileSystem]​

Annotated Example​

Global Settings​

[debug]​

[terminal]​

[tunnel]​

[tunnel.services]​

[tunnel.cert]​

[stats]​

[users]​

[commands]​

[fileSystem]​

Value Types

Global Settings

`[debug]`

`[terminal]`

`[tunnel]`

SFTP

`[tunnel.services]`

`[tunnel.cert]`

`[stats]`

`[users]`

`[commands]`

Structure

Events

Macros

Async Mode

Syntax

`[fileSystem]`

Annotated Example

Global Settings

`[debug]`

`[terminal]`

`[tunnel]`

`[tunnel.services]`

`[tunnel.cert]`

`[stats]`

`[users]`

`[commands]`

`[fileSystem]`