Controller Configuration

Last updated: June 5, 2026Latest Frontend Version: 2.17.0

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

Image Configuration Structure

Global Settings

These options are specified at the top level of the configuration file.

FIPSModeOff

If set to true, disables FIPS mode for the VM controller.

ControllerSubvariant

Allows selecting a different controller binary to download instead of the default.

By default, the VMC Stub obtains the controller from http://vmc.ticrypt/<arch>/<os>/<variant> (or http://vmc-test.ticrypt/<arch>/<os>/<variant> for test versions). If a non-empty subvariant is specified, the VMC Stub will attempt to fetch from http://vmc.ticrypt/<arch>/<os>/<variant>/<subvariant> instead. Falls back to the default if the subvariant cannot be obtained.

ConfigPrefix

Allows selecting a different image configuration file instead of the default.

By default, the VMC Stub loads the image configuration from the standard path above. If a ConfigPrefix is passed in the preregistration parameters, the VMC Stub will try to load <config-path>/<configprefix>-controller.toml instead. Falls back to the default if the specified configuration cannot be loaded.

Debug Configuration

Parameter	Description
`logLevel`	Log verbosity. Valid values: `"trace"`, `"debug"`, `"info"`, `"warn"`, `"error"`, `"fatal"`, `"panic"`. Default: `"info"`
`enableManagerSudo`	If `true`, allows VM managers to run sudo commands. Disabled by default

Antivirus Configuration

Parameter	Description
`clamAVEnabled`	If `true`, enables ClamAV antivirus scanning. Default: `false`

Terminal Configuration

Configuration parameters for running terminal-based applications. Applications started in this mode can be interacted with from the client.

Parameter	Description
`enabled`	Whether the terminal service is enabled
`defaultCommand`	The default shell command to use. Platform-specific default (e.g. `/bin/bash`, `powershell.exe`)
`scrollback`	Default number of lines of scrollback history to keep
`maxScrollback`	Maximum number of lines of scrollback history

Tunnel Configuration

Configuration parameters for TLS-tunneled TCP connections to configured applications.

Parameter	Description
`enabled`	Whether the tunnel service is enabled
`serverPort`	TCP port on which to bind the tunneling service. Default: `22`
`allowedPorts`	List of ports allowed for tunneling. May be a single port, a range (e.g. `"5901-5905"`), or an array of ports
`tunlsLogLevel`	Log level for tunnel messages. See values below. Default: `Errors`
`addGroups`	System groups that users with tunneling permissions will be added to
`idleTimeout`	If non-zero, tunnels with no active forwarded connections are killed after this duration. Minimum non-zero value: `1s`. Default: `15m`
`sftpEnabled`	If `true`, enables SFTP support via an SSH daemon configured for SFTP-only connections
`sftpPort`	Local port for the SFTP SSH daemon. Automatically added to `allowedPorts`. Default: `2022`
`sshDirPath`	Path to the directory containing `sshd` and `ssh-keygen` executables. If unset, checks the assets archive at `bin/ssh/` then the system path

tunlsLogLevel values:

Value	Level
`0`	None
`1`	Errors
`2`	Warnings
`3`	Info
`4`	Debug

`[tunnel.services]`

Optional names for ports, which may be referenced in VM connection instructions.

`[tunnel.cert]`

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

Parameter	Description
`country`	Two-letter country code (required if specified)
`organization`	Organization name for the certificate

Stats Configuration

Parameter	Description
`systemInterval`	How often to poll system stats. Default: `1s`
`logErrors`	Whether to log errors from retrieving system stats. Default: `false`. (Timeouts occur relatively frequently on Windows under heavy load.)

User Configuration

Options related to users and profiles.

Parameter	Description
`dontChangeAdminPassword`	If `true`, the VMC will not attempt to change the admin password at startup
`adminAccess`	If unset or `false`, no user (including the owner) has Admin/Sudo on the VM. If `true`, the VM owner has Admin/Sudo on the VM. Default: `false`. See VM Installer 3.10.42
`managersAsAdmin`	If `true`, managers with Sudo permissions will also be added to the Admin group. Only has an effect if `adminAccess` is `true`. Default: `false`
`createDirs`	Directories to automatically create in the user's home on their encrypted drive if they do not already exist
`createHiddenDirs`	Hidden directories to automatically create in the user's home
`passwordLength`	Length of the randomly generated user password. Default: `32`
`userProfileLinkType`	Link type for Windows user profile directories. Possible values: `"junction"`, `"softlink"`. Default: `"junction"`

Commands Configuration

Enables the VM image creator to define commands or scripts to run at specific VM lifecycle stages.

Structure

[commands.rootCommands] -- Commands run as root.
- runOnlyOnceCommands -- Run only once. Re-runs on each stage trigger until the command succeeds.
- runEveryTimeCommands -- Run every time the stage is triggered.
[commands.userCommands] -- Commands run as the current user.
- runOnlyOnceCommands -- Same as above.
- runEveryTimeCommands -- Same as above.

Dynamic Parameters

Commands may include dynamic parameters using the @:parameterName: syntax. The VM Controller substitutes the correct value at runtime.

Supported events and available parameters:

Event	Parameters
`on_login`	`@:user:`
`on_homeDriveAttached`	(none)
`on_driveAttached`	`@:driveName:`, `@:driveSlot:`, `@:driveType:`
`on_vpnConnected`	(none)

note

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

Async Commands

To run a command asynchronously, append -async to the event name:

on_driveAttached-async = {setENV = "export DRIVEASYNC=@:driveSlot:"}

Syntax

event_name = {command0_name = "command0", command1_name = "command1"}

Examples:

on_login = {setXdgRuntimeDir = "install -o @:user: -m 700 -d /run/user/$(id -u @:user:)", dockerGroup = "usermod -aG docker @:user:"}
on_driveAttached = {setENV = "export DRIVE=@:driveName:"}

VM Image Configuration Example

View complete controller.toml example

controller.toml
FIPSModeOff = true

[debug]
# Defines the level of logs that will be printed by the VMC.
# Possible values are: "trace", "debug", "info", "warn", "error", "fatal", "panic"
# Default value is "info"
#logLevel = "info"

# Managers of the VMC can be allowed to run sudo commands. This is disabled by default.
#enableManagerSudo = false


[terminal]
# Whether or not the terminal service is enabled.
enabled = true

# The default command to use when running terminals.
# Default is platform-specific.
#command = "/bin/bash"
#command = "powershell.exe"

# Default number of lines of scrollback history kept.
#scrollback = 10000
#maxScrollback = 100000


[antivirus]
clamAVEnabled = false


# A TunnelConfig contains configuration parameters for TLS-tunneled TCP
# connections to configured applications.
[tunnel]
# Whether or not the tunnel service is enabled.
enabled = true

# TCP port on which to bind the tunneling service.
#serverPort = 22

# List of allowed ports for tunneling.
# May be a single port, a range of ports, or an array of ports.
#allowedPorts = []  # default
#allowedPorts = 5901
#allowedPorts = "5901-5905"
#allowedPorts = [ 14500, 5901 ]

# If specified, the log level to use for tunls log messages. Messages will
# only be logged if the log level is <= the configured value.
#
# Valid values are:
#   - None     = 0
#   - Errors   = 1
#   - Warnings = 2
#   - Info     = 3
#   - Debug    = 4
#
# If no log level is specified, the Errors log level will be used.
#tunlsLogLevel = "info"  # default

# List of additional system groups that users with tunneling permissions will be
# added to.
#addGroups = []     # default
#addGroups = [ "Remote Desktop Users" ]  # Windows: allow access to RDP

# Timeout for idle tunnels.
# If set to a positive duration, tunnels without active forwarded connections
# will be killed after the specified timeout.
#
# The minimum non-zero idle timeout is 1 second.
#
# Default: 15 minutes
#idleTimeout = "15m"

# Whether SFTP support is enabled.
# If enabled, an SSH daemon will be run that is configured to only allow
# SFTP connections.
sftpEnabled = true

# The local port on which the SFTP SSH daemon runs.
# This will be automatically added to the allowed tunnel ports.
sftpPort = 2022

# The path to the directory containing the sshd(.exe) and ssh-keygen(.exe) executables.
# If not set, the following will be checked:
#
#   1. The assets archive at bin/ssh/
#   2. The system path
#sshDirPath = ""

# Optional names for ports, which may be referred to in the connection
# instructions for the VM.
[tunnel.services]
#vnc = 5901
#xpra = 14500

# Options for the self-signed TLS certificate generated by the tunneling service.
[tunnel.cert]
# If specified, country MUST be a two-letter country code.
#country = "US"
#organization = "unspecified"


[stats]
# How often to poll system stats. Default is 1 second.
#systemInterval =


# User configuration
[users]
# If true, the VMC will not attempt to change the admin password at startup.
dontChangeAdminPassword = true

# If unset or false, no user (including the owner) has Admin/Sudo on the VM.
# If true, the VM owner has Admin/Sudo on the VM.
#adminAccess = false

# If true, managers with Sudo permissions will also be added to the Admin group.
# This only has an effect if adminAccess is true.
#managersAsAdmin = false

# Directories to automatically create in the user's home on their encrypted drive
# if they do not already exist. This allows directories to be linked into the user's
# profile on the C: drive even if they did not originally exist.
#createDirs = []
#createHiddenDirs = []

# Password length of the random password created for users.
#passwordLength = 32

# Link type for Windows user profile directories.
# Possible values are "junction" and "softlink".
# Default value is "junction".
#userProfileLinkType = "junction"


# Commands
[commands]

[commands.rootCommands]
[commands.rootCommands.runOnlyOnceCommands]
# ...
[commands.rootCommands.runEveryTimeCommands]
# This feature enables the creator of the VM Image to define commands or scripts
# to run at certain stages of the VM.
#
# Dynamic parameters can be passed using the @:parameterName: syntax.
# Supported events and tags:
#   "on_login"              : {@:user:}
#   "on_homeDriveAttached"  : {}
#   "on_driveAttached"      : {@:driveName:, @:driveSlot:, @:driveType:}
#   "on_vpnConnected"       : {}
#
# When a home drive is attached, both on_homeDriveAttached and on_driveAttached
# are triggered in that order.
#
# Syntax:
#   event_name = {command0_name = "command0", command1_name = "command1"}
#
# Examples:
#   on_login = {setXdgRuntimeDir = "install -o @:user: -m 700 -d /run/user/$(id -u @:user:)", dockerGroup = "usermod -aG docker @:user:"}
#   on_driveAttached = {setENV = "export DRIVE=@:driveName:"}
#
# To run a command asynchronously, append "-async" to the event name:
#   on_driveAttached-async = {setENV = "export DRIVEASYNC=@:driveSlot:"}

[commands.userCommands]
[commands.userCommands.runOnlyOnceCommands]
# ...
[commands.userCommands.runEveryTimeCommands]
# ...

Value Types​

Global Settings​

[debug]​

[terminal]​

[tunnel]​

SFTP​

[tunnel.services]​

[tunnel.cert]​

[stats]​

[users]​

[commands]​

Structure​

Events​

Macros​

Async Mode​

Syntax​

[fileSystem]​

Image Configuration Structure​

Global Settings​

FIPSModeOff​

ControllerSubvariant​

ConfigPrefix​

Debug Configuration​

Antivirus Configuration​

Terminal Configuration​

Tunnel Configuration​

[tunnel.services]​

[tunnel.cert]​

Stats Configuration​

User Configuration​

Commands Configuration​

Structure​

Dynamic Parameters​

Async Commands​

Syntax​

VM Image Configuration Example​

Value Types

Global Settings

`[debug]`

`[terminal]`

`[tunnel]`

SFTP

`[tunnel.services]`

`[tunnel.cert]`

`[stats]`

`[users]`

`[commands]`

Structure

Events

Macros

Async Mode

Syntax

`[fileSystem]`

Image Configuration Structure

Global Settings

FIPSModeOff

ControllerSubvariant

ConfigPrefix

Debug Configuration

Antivirus Configuration

Terminal Configuration

Tunnel Configuration

`[tunnel.services]`

`[tunnel.cert]`

Stats Configuration

User Configuration

Commands Configuration

Structure

Dynamic Parameters

Async Commands

Syntax

VM Image Configuration Example