Configuration Reference

Host settings panel — The host detail settings panel where the per-host runtime values (enabled toggle, heartbeat and reconciliation intervals, metric collection toggles) are edited.

This page documents every real configuration option. The static options come from the Trailer binary’s config file and CLI flags. The dynamic options are per-host runtime settings stored on the server.

Static configuration

Static config controls how a Trailer process starts: where its data lives, which server it talks to, and how it builds images. It is read from a YAML file and can be overridden by CLI flags.

Config file location

The default config file is:

~/.config/trailer.dev/config.yml

The exact base directory follows the XDG spec ($XDG_CONFIG_HOME/trailer.dev/config.yml). Override the path with the --config-file / -C flag.

If the file does not exist on startup, Trailer creates it automatically, populated with the current flag values (defaults unless you passed flags).

Config file format

The file is a flat YAML document. There is no server: / agent: / dynamic: nesting. Keys map directly to the static options:

server_url: http://localhost:8090
deployment_name: my-host
data_directory: trailer_data
build_directory: /tmp
delete_build_context_after_build: true
license_key: ""
instance_id: ""
log_directory: /home/you/.local/state/trailer.dev
log_max_size: 10485760

Options

YAML key	Flag	Short	Default	Description
`server_url`	`--server-url`	`-S`	`http://localhost:8090`	Address of the Trailer server instance the agent connects to.
`deployment_name`	`--deployment-name`	`-D`	machine hostname	Name shown for the deployed agent in the connected instance.
`build_directory`	`--build-directory`	`-b`	`/tmp`	Directory the agent uses when building container images.
`data_directory`	`--data-directory`	`-d`	`trailer_data`	Directory for the Trailer server database.
`delete_build_context_after_build`	`--delete-build-context-after-build`	`-B`	`true`	Delete the build context after building a workspace image.
`license_key`	`--license-key`	`-L`	empty	License key (optional).
`instance_id`	`--instance-id`	`-i`	empty	Instance identifier for the license (optional).
`log_directory`	`--log-directory`	(none)	`$XDG_STATE_HOME/trailer.dev`	Directory for agent log files.
`log_max_size`	`--log-max-size`	(none)	`10485760` (10 MiB)	Maximum total size of agent log files, in bytes.

The config-file path itself is set with --config-file / -C and is not stored in the file.

Two fields are intentionally not config-file options. The agent token is derived from a protected machine ID at runtime, and the log output writer is internal. Neither is user-settable through YAML.

Which flags apply to which mode

Trailer runs as a server, an agent, or both (standalone). Each mode hides the flags that do not apply to it. The flags still exist on every binary, they are just hidden from that mode’s --help.

Flag	Server	Agent	Standalone
`--build-directory`	hidden	shown	shown
`--deployment-name`	hidden	shown	shown
`--delete-build-context-after-build`	hidden	shown	shown
`--data-directory`	shown	hidden	shown
`--license-key`	shown	hidden	shown
`--instance-id`	shown	hidden	shown
all other flags	shown	shown	shown

Precedence

Configuration resolves in two layers:

flowchart LR
  A["Config file values<br/>(or written defaults on first run)"] --> B["CLI flag<br/>(only when explicitly set)"]
  B --> C["Effective config"]

The config file is loaded (or created from flag defaults if absent).
A CLI flag overrides the file value only when that flag is explicitly passed.

There is no environment-variable layer for static config. The static options above come only from the config file and CLI flags. Server-wide settings (admin bootstrap, SMTP, backups, file storage) are a separate system configured through environment variables. See Environment variables below.

As a small exception, log_directory and log_max_size fall back to their flag defaults when an existing config file omits them.

Example

trailer server --server-url http://localhost:8090 --data-directory ./trailer_data
trailer agent --server-url https://trailer.example.com --build-directory /var/tmp/builds

See Installation for how to obtain and run the binary.

Environment variables

Separate from the static config file, the server reads a set of environment variables to configure server-wide settings that are stored in the database: the initial admin account, the application name and URL, email (SMTP), scheduled backups, and file storage. These apply to the server (and to standalone mode). A standalone agent does not use them.

How and when they apply

This is the part that trips people up. There are two timings:

One-time, on first start. A few variables are read only the very first time the server starts, to seed the database. After that the database is the source of truth, and changing the variable has no further effect. This covers the application name and the initial admin account.
Every start (sticky override). The rest are read on every server start. When a variable is set, its value overrides whatever is stored (including changes you made in the web UI), and the new value is saved. When a variable is unset, the stored value is kept.

Two consequences of the every-start behavior:

Setting one of these pins the value. Edits made in the UI are overwritten on the next restart while the variable is still set.
Removing a variable later does not reset the setting to a default. It just leaves the last applied value in place.

The two timings can apply to closely related settings. For example TRAILER_APP_NAME is one-time, but TRAILER_APP_URL is re-applied on every start.

Boolean variables are enabled by setting them to the exact string true. Any other value, or leaving them unset, is treated as off.

Initial admin account (one-time)

On the first server start, if no user exists yet and both the admin email and password are set, an administrator account is created from these:

Variable	Purpose	Default
`TRAILER_APP_ADMIN_EMAIL`	Admin email. Required to create the admin.	empty
`TRAILER_APP_ADMIN_PASSWORD`	Admin password. Required to create the admin.	empty
`TRAILER_APP_ADMIN_USERNAME`	Admin username.	`admin`
`TRAILER_APP_ADMIN_DISPLAY_NAME`	Admin display name.	`admin`

This bootstrap happens only on the first start. If you start the server once without the admin email and password set, the environment-variable bootstrap is already spent. Set these before the very first start, or create the first user through the web interface instead (see First User Setup).

Application

Variable	Purpose	Timing	Default
`TRAILER_APP_NAME`	Application name shown in the UI.	One-time	`Trailer.dev`
`TRAILER_APP_URL`	Public base URL of the server.	Every start	`http://localhost:8090`

Email (SMTP)

All read on every start. You can also set these in the Settings screen, but a variable that is set overrides the UI on the next restart.

Variable	Purpose
`TRAILER_APP_SMTP_ENABLED`	Enable SMTP (set to `true`).
`TRAILER_APP_SMTP_SERVER_HOST`	SMTP server host.
`TRAILER_APP_SMTP_SERVER_PORT`	SMTP server port.
`TRAILER_APP_SMTP_USERNAME`	SMTP username.
`TRAILER_APP_SMTP_PASSWORD`	SMTP password.
`TRAILER_APP_SMTP_TLS`	Use TLS (set to `true`).
`TRAILER_APP_SMTP_AUTH_METHOD`	Authentication method.
`TRAILER_APP_SMTP_HELO_DOMAIN`	HELO/EHLO domain name.
`TRAILER_APP_SMTP_SENDER_ADDRESS`	From address for outgoing mail.
`TRAILER_APP_SMTP_SENDER_NAME`	From name for outgoing mail.

Scheduled backups

All read on every start.

Variable	Purpose
`TRAILER_BACKUPS_CRON`	Cron schedule for automatic backups.
`TRAILER_BACKUPS_TO_KEEP`	Number of automatic backups to retain.
`TRAILER_BACKUPS_S3_ENABLED`	Store backups in S3-compatible storage (set to `true`).
`TRAILER_BACKUPS_AWS_ACCESS_KEY_ID`	S3 access key ID.
`TRAILER_BACKUPS_AWS_SECRET_ACCESS_KEY`	S3 secret access key.
`TRAILER_BACKUPS_AWS_ENDPOINT_URL_S3`	S3 endpoint URL.
`TRAILER_BACKUPS_AWS_REGION`	S3 region.
`TRAILER_BACKUPS_BUCKET_NAME`	S3 bucket name.
`TRAILER_BACKUPS_PATH_STYLE_ADDRESSING`	Use path-style S3 addressing (set to `true`).

File storage

S3-compatible storage for uploaded files. All read on every start.

Variable	Purpose
`TRAILER_UPLOADS_S3_ENABLED`	Store uploads in S3-compatible storage (set to `true`).
`TRAILER_UPLOADS_AWS_ACCESS_KEY_ID`	S3 access key ID.
`TRAILER_UPLOADS_AWS_SECRET_ACCESS_KEY`	S3 secret access key.
`TRAILER_UPLOADS_AWS_ENDPOINT_URL_S3`	S3 endpoint URL.
`TRAILER_UPLOADS_AWS_REGION`	S3 region.
`TRAILER_UPLOADS_BUCKET_NAME`	S3 bucket name.
`TRAILER_UPLOADS_PATH_STYLE_ADDRESSING`	Use path-style S3 addressing (set to `true`).

Database encryption key

Variable	Purpose
`TRAILER_DB_ENCRYPTION_KEY`	Key used to encrypt sensitive settings in the database. If you set it, it must stay the same across restarts, otherwise the stored settings cannot be read. Treat it as a secret and keep a backup.

Dynamic configuration

Dynamic config is the set of per-host runtime settings managed by the server. These are not in the config file and have no CLI flags. The server stores them on each host record and pushes them to the agent at registration and on every heartbeat. Edit them from the host detail page in the UI. See Host details.

Setting	Meaning
Host enabled	Whether the host is enabled. When off, the agent stops reconciling.
Heartbeat interval	How often the agent reports to the server, in seconds.
Reconciliation interval	How often the agent reconciles desired state against the runtime, in seconds.
Collect GPU metrics	Collect GPU metrics on this host.
Collect host metrics	Collect host-level metrics.
Collect workspace metrics	Collect per-workspace metrics.

Because these values arrive over the heartbeat, changes take effect without restarting the agent.