Configuration reference

Configuration keys and command-line options for Goauld

This page explains the configuration model and links to the complete generated configuration files. Every runtime key can also be supplied as a command-line option. The environment variable is formed by uppercasing the option name, replacing - with _, and adding the component prefix: GOAULD_ for the server and agent, TEALC_ for the client.

For precedence and configuration-file locations, see Variables and Configuration files.

Complete generated configuration

These files are generated from the main Goauld repository’s configuration definitions. They include every supported key, default, and source comment:

From the documentation repository, regenerate them with:

./scripts/update-config-reference.sh /path/to/Goauld

The generated files are reference snapshots for the latest documented release. Do not edit them by hand.

Server: common settings

Key	Type	Environment variable	Purpose
`age-private-key`	string	`GOAULD_AGE_PRIVATE_KEY`	Server age private key. Keep it secret.
`http-domain`	list	`GOAULD_HTTP_DOMAIN`	HTTP/WebSocket hostnames.
`tls-domain`	list	`GOAULD_TLS_DOMAIN`	Raw TLS transport hostnames.
`dns-domain`	string	`GOAULD_DNS_DOMAIN`	DNS transport domain.
`dns-domain-alt`	string	`GOAULD_DNS_DOMAIN_ALT`	Alternate DNS transport domain.
`http-listen-addr`	address	`GOAULD_HTTP_LISTEN_ADDR`	HTTP listener, for example `:80`.
`https-listen-addr`	address	`GOAULD_HTTPS_LISTEN_ADDR`	HTTPS listener.
`sshd-listen-addr`	address	`GOAULD_SSHD_LISTEN_ADDR`	Direct SSH listener, for example `:2222`.
`dns-listen-addr`	address	`GOAULD_DNS_LISTEN_ADDR`	DNS listener.
`quic-listen-addr`	address	`GOAULD_QUIC_LISTEN_ADDR`	QUIC listener.
`tls`	boolean	`GOAULD_TLS`	Enable TLS support.
`quic`	boolean	`GOAULD_QUIC`	Enable QUIC; TLS must also be enabled.
`dns`	boolean	`GOAULD_DNS`	Enable SSH over DNS.
`ssh`	boolean	`GOAULD_SSH`	Enable the direct SSH listener.
`access-token`	list	`GOAULD_ACCESS_TOKEN`	Token for `/manage/` and optionally `/ssh-ws/`.
`admin-token`	list	`GOAULD_ADMIN_TOKEN`	Token for `/admin/`.
`allowed-ips`	list	`GOAULD_ALLOWED_IPS`	IPs/CIDRs allowed to use operator endpoints.
`trusted-proxies`	list	`GOAULD_TRUSTED_PROXIES`	Proxies trusted to provide `X-Forwarded-For`.
`ssh-websocket`	boolean	`GOAULD_SSH_WEBSOCKET`	Enable the HTTP(S)-tunneled SSH endpoint.
`no-db`	boolean	`GOAULD_NO_DB`	Disable database persistence.
`db-file-name`	path	`GOAULD_DB_FILE_NAME`	SQLite database path.
`binaries-path`	path	`GOAULD_BINARIES_PATH`	Directory containing agent binaries.
`binaries-basic-auth`	string	`GOAULD_BINARIES_BASIC_AUTH`	Basic Auth for binary downloads.

Client (`tealc`): common settings

Key	Type	Environment variable	Purpose
`server`	URL	`TEALC_SERVER`	HTTP server used by the client API.
`ssh-server`	address	`TEALC_SSH_SERVER`	Direct server SSH address.
`ws`	boolean	`TEALC_WS`	Use SSH over the server’s WebSocket endpoint.
`access-token`	string	`TEALC_ACCESS_TOKEN`	Token for `/manage/`.
`admin-token`	string	`TEALC_ADMIN_TOKEN`	Token for `/admin/`.
`insecure`	boolean	`TEALC_INSECURE`	Skip TLS certificate verification. Avoid in production.
`wait-timeout`	seconds	`TEALC_WAIT_TIMEOUT`	Time to wait for an agent to come online.
`config-file`	path	`TEALC_CONFIG_FILE`	Explicit configuration file.
`password`	string	`TEALC_PASSWORD`	Agent static password. Prefer prompting.
`prompt`	boolean	`TEALC_PROMPT`	Prompt for the agent password.
`save-password`	boolean	`TEALC_SAVE_PASSWORD`	Save the password in the client config.
`control-master`	boolean	`TEALC_CONTROL_MASTER`	Reuse an SSH connection.
`verbose`	counter	`TEALC_VERBOSE`	Increase client logging.
`quiet`	boolean	`TEALC_QUIET`	Suppress client logging.

Command-specific options are documented with each command, including SSH, file transfer, and forwarding.

Agent runtime configuration

The linked agent configuration snapshot documents the agent’s runtime YAML keys. The same values can be supplied as CLI options or as GOAULD_* environment variables. For example:

server: http://goauld.example.com
ssh-server: goauld.example.com:2222
rssh-order:
  - SSH
  - WS
keepalive: 20

Runtime values override defaults compiled into the binary. See Variables for the complete precedence order.

See Working days for weekday and activity-window scheduling, and Killswitch for duration and fixed-date termination rules.

Agent compile-time defaults

tealc compile --env accepts a separate build-variable file. These variables are embedded into the resulting binary as defaults and are not read from the agent process environment at runtime. Examples include:

AGENT__AGE_PUBLIC_KEY=age1...
AGENT__NAME=operator-defined-name
HTTP_DOMAIN=goauld.example.com
HTTP_PORT=80
SSHD_PORT=2222

Available build variables depend on the features enabled at compile time. Use tealc compile --drop-env to generate the complete build template for the current source tree. See Compile agent for build targets and examples.

Security-sensitive settings

Treat these values as secrets:

age-private-key
access-token
admin-token
password
binaries-basic-auth

Do not enable insecure in a production client, do not expose the admin API without IP restrictions or equivalent network controls, and do not commit configuration files containing real credentials.