Tarsus Configuration

Tarsus Configuration

Configure the Tarsus client agent.

Configuration File

TARSUS_CONFIG names the config file outright: when it is set, that file is the only one read, and Tarsus fails to start if it is missing.

Otherwise Tarsus layers whichever of these exist, each overriding the one before:

1. tarsus.toml in the current directory
2. ~/.config/mantis/tarsus.toml (platform-dependent config directory)
3. /etc/mantis/tarsus.toml

These are layers, not a first-match search: a key set in /etc/mantis/tarsus.toml wins over the same key in the user config directory or the current directory, so a file an unprivileged user can write cannot change what the deployed service does. If no file is found, defaults are used.

Environment variables are applied on top of the file. Every setting is reachable that way — the key is TARSUS__ followed by the section and field names in upper case, joined by double underscores (TARSUS__POLL__INTERVAL_SECS for [poll] interval_secs) — so the table below is the common subset, not the limit. Any TARSUS__* key that is not a setting is a hard startup error, not a silent override. Two further limits apply — the [security] section can never be set from the environment, and when minimum_transport_level = "wireguard" the WireGuard floor is checked after env vars, so TARSUS__TRANSPORT__ENABLED=false (or enabled = false in the file) makes Tarsus refuse to start rather than run below the mandated level.

Configuration Sections

Top-Level Fields

name = "web-server-01"
mode = "listen"
data_dir = "/var/lib/tarsus"
log_level = "info"

Field	Type	Default	Required	Description
name	string	hostname	No	Client name for registration. Env: TARSUS__NAME
mode	string	"listen"	No	Operating mode: listen (server connects to client) or poll (client polls server). Env: TARSUS__MODE
data_dir	string	platform data dir + /tarsus	No	Data directory for certificates and state. Env: TARSUS__DATA_DIR
log_level	string	"info"	No	Log level: trace, debug, info, warn, error. Env: TARSUS__LOG_LEVEL

[tls]

TLS configuration. TLS is always enabled and cannot be disabled.

[tls]
cert_path = "/etc/mantis/certs/client.crt"
key_path = "/etc/mantis/certs/client.key"
ca_cert_path = "/etc/mantis/certs/ca.crt"
server_name = "thorax.example.com"

Field	Type	Default	Required	Description
cert_path	string	-	No	Client certificate PEM file. If not set, auto-generated. Env: MANTIS_TLS_CERT_PATH
key_path	string	-	No	Client private key PEM file. Must be set with cert_path. Env: MANTIS_TLS_KEY_PATH
ca_cert_path	string	-	Yes	CA certificate for server verification. Env: MANTIS_TLS_CA_CERT_PATH
enrollment_address	string	-	Conditional	The assigned Thorax’s CSR-enrollment address as host:port. Required when a registration token is set: nothing derives it, and without it Tarsus warns, skips enrollment and falls back to a self-signed thumbprint-mode certificate. Env: TARSUS__TLS__ENROLLMENT_ADDRESS
server_name	string	-	No	Server name for SNI validation

Note

Tarsus verifies both servers it dials — Mandible and its assigned Thorax — against the CA in ca_cert_path, which is required in every mode. When cert_path and key_path are not set, Tarsus auto-generates a self-signed certificate to present as its own identity; that changes what the server sees, not how Tarsus decides to trust the server.

[mandible]

Mandible connection settings (registration + heartbeat). Tarsus registers with Mandible’s internal gRPC endpoint; Mandible’s response assigns the Thorax instance responsible for command execution. In poll mode Tarsus then connects outbound to that Thorax to fetch commands; in listen mode (the default) Tarsus exposes a gRPC server and the assigned Thorax connects inbound.

[mandible]
endpoint = "mandible.example.com:50052"
connect_timeout_secs = 30
request_timeout_secs = 360

Field	Type	Default	Required	Description
endpoint	string	"localhost:50052"	No	Mandible internal gRPC endpoint for registration (hostname:port) — this is the gRPC server port (50052), not the REST API port (3000). Env: TARSUS__MANDIBLE__ENDPOINT
connect_timeout_secs	integer	30	No	Connection timeout in seconds
request_timeout_secs	integer	360	No	Request timeout in seconds. Must exceed Thorax’s command timeout (300s); default is 300s + 60s buffer.

[listen]

Listen mode configuration (when mode = "listen").

[listen]
address = "0.0.0.0"
port = 9342

Field	Type	Default	Required	Description
address	string	"0.0.0.0"	No	Bind address. Env: TARSUS__LISTEN__ADDRESS
port	integer	9342	No	Listen port. Env: TARSUS__LISTEN__PORT

[poll]

Poll mode configuration (when mode = "poll").

[poll]
interval_secs = 30
max_commands = 10
command_timeout_secs = 3600

Field	Type	Default	Required	Description
interval_secs	integer	30	No	Polling interval in seconds. Env: TARSUS__POLL__INTERVAL_SECS
max_commands	integer	10	No	Maximum commands to fetch per poll
command_timeout_secs	integer	3600	No	Timeout for a command dispatched without one of its own, when the server sends no configuration

[registration]

Registration and heartbeat configuration.

[registration]
enabled = true
heartbeat_interval_secs = 30
token = "your-registration-token"

[registration.tags]
role = "web-server"
region = "us-east-1"

[registration.labels]
team = "platform"

Field	Type	Default	Required	Description
enabled	boolean	true	No	Enable registration with server
heartbeat_interval_secs	integer	30	No	Heartbeat interval. Env: TARSUS__REGISTRATION__HEARTBEAT_INTERVAL_SECS
tags	map	{}	No	Key-value tags for deployment filtering
labels	map	{}	No	Custom metadata labels
token	string	-	No	Registration token for automated approval (Octopus-style). Env: TARSUS__REGISTRATION__TOKEN

RegistrationConfig is #[serde(deny_unknown_fields)], so those five keys are the whole section — any other key makes the agent fail to parse its config and refuse to start. Registration retries are not configured here: they use the shared [retry] section below (max_retries, initial_delay_ms, max_delay_ms, backoff_multiplier, retry_indefinitely, failure_threshold).

Critical Security

Registration tokens provide automatic client approval - high privilege access.

• NEVER commit tokens to version control
• Use environment variable TARSUS__REGISTRATION__TOKEN instead of config file
• Generate short-lived, single-use tokens per deployment
• Monitor for unexpected client registrations
• Revoke tokens immediately after use

[retry]

Connection retry configuration.

[retry]
max_retries = 3
initial_delay_ms = 1000
max_delay_ms = 60000
backoff_multiplier = 2.0
retry_indefinitely = true
failure_threshold = 5

Field	Type	Default	Required	Description
max_retries	integer	3	No	Max retries before resetting backoff
initial_delay_ms	integer	1000	No	Initial delay before first retry (ms)
max_delay_ms	integer	60000	No	Maximum delay between retries (ms)
backoff_multiplier	float	2.0	No	Exponential backoff multiplier
retry_indefinitely	boolean	true	No	Keep retrying after max_retries (with max_delay). Set false only for testing
failure_threshold	integer	5	No	Consecutive failures before opening circuit

[console]

Tokio-console settings for async runtime debugging. Only active when the tokio-console feature is enabled.

[console]
enabled = true
address = "127.0.0.1"
port = 6671
retention_secs = 60
publish_interval_ms = 1000

Field	Type	Default	Required	Description
enabled	boolean	false	No	Enable the tokio-console server. false whether or not a config file loads, and whether or not it carries a [console] table: the debug listener is opt-in and needs this set explicitly. Env: TARSUS__CONSOLE__ENABLED
address	string	"127.0.0.1"	No	Bind address. Env: TARSUS__CONSOLE__ADDRESS
port	integer	6671	No	Console port. 6671 with no config file and with a file that omits [console]; the sentinel 0 applies only when the table is present and port alone is omitted. Env: TARSUS__CONSOLE__PORT
retention_secs	integer	60	No	How long to retain completed task data. Env: TARSUS__CONSOLE__RETENTION_SECS
publish_interval_ms	integer	1000	No	Update interval for connected clients (ms). Env: TARSUS__CONSOLE__PUBLISH_INTERVAL_MS
recording_path	string	-	No	Path to record console data for offline analysis. Env: TARSUS__CONSOLE__RECORDING_PATH

[transport]

WireGuard-based transport configuration for encrypted connectivity. When enabled, Tarsus uses the WireGuard overlay assigned during registration. The relay endpoint (for NAT traversal fallback) is supplied by Mandible at registration time — it is not a config field.

[transport]
enabled = true
private_key_path = "/etc/mantis/wireguard/private.key"
key_rotation_interval_secs = 0

Field	Type	Default	Required	Description
enabled	boolean	false	No	Enable WireGuard transport. Env: TARSUS__TRANSPORT__ENABLED
private_key_path	string	-	No	WireGuard private key file. If not set, keys are auto-generated in data_dir. Env: TARSUS__TRANSPORT__PRIVATE_KEY_PATH
key_rotation_interval_secs	integer	0	No	Interval at which the agent rotates its WireGuard static key over the live overlay. 0 disables periodic rotation. Env: TARSUS__TRANSPORT__KEY_ROTATION_INTERVAL_SECS
relay_expected_identity	string	-	No	Relay identity to pin — the agent refuses to sign an authentication response for any other. The relay announces the Thorax instance’s name. Unset leaves the relay authenticated by TLS alone. Env: TARSUS__TRANSPORT__RELAY_EXPECTED_IDENTITY

[execution]

The commands and scripts the agent runs.

[execution]
inherit_env = ["JAVA_HOME", "HTTPS_PROXY"]

Field	Type	Default	Required	Description
inherit_env	array	[]	No	Host environment variables a command or script inherits besides the base set. Env: TARSUS__EXECUTION__INHERIT_ENV (comma-separated)

A command or script runs with only the base set of this agent’s environment — PATH, HOME, USER, LOGNAME, SHELL, LANG, LANGUAGE, LC_*, TZ, TMPDIR, TERM, and on Windows the system and profile variables a process needs to start — plus the variables the action and deployment define. Name anything else it needs in inherit_env; Mantis’s own variables (MANTIS_*, MANDIBLE__*, THORAX__*, TARSUS__* and DATABASE_URL) are refused there, and the agent does not start. Its process tree is stopped as a whole at a timeout or a cancellation.

[security]

Security configuration for protected settings. Settings in this section cannot be overridden by environment variables, preventing configuration injection attacks.

[security]
minimum_transport_level = "wireguard"

Field	Type	Default	Required	Description
minimum_transport_level	string	"none"	No	Minimum transport security: none (env override allowed) or wireguard (env override blocked)

Danger

When minimum_transport_level = "wireguard", a config that disables WireGuard transport, whether through the file or the TARSUS__TRANSPORT__ENABLED environment variable, is refused and Tarsus does not start. This prevents attackers with access to environment variables from downgrading transport security.

Environment Variables

Every field in the tables above has an environment key, derived mechanically from its section and name: TARSUS__<SECTION>__<FIELD>, upper case. The keys below are the ones an operator reaches for most often; a field that is not listed here still has one, and the per-section tables give it.

Environment Variable	Description
TARSUS_CONFIG	Path to config file (single underscore; not a setting)
TARSUS__NAME	Client name
TARSUS__MODE	Operating mode (listen or poll)
TARSUS__LOG_LEVEL	Log level
TARSUS__DATA_DIR	Data directory
TARSUS__MANDIBLE__ENDPOINT	Server address (hostname:port)
TARSUS__MANDIBLE__CONNECT_TIMEOUT_SECS	Connect timeout to Mandible (seconds)
TARSUS__MANDIBLE__REQUEST_TIMEOUT_SECS	Request timeout to Mandible (seconds)
TARSUS__LISTEN__ADDRESS	Listen bind address
TARSUS__LISTEN__PORT	Listen port
TARSUS__POLL__INTERVAL_SECS	Poll interval (seconds)
TARSUS__POLL__MAX_COMMANDS	Commands fetched per poll
TARSUS__REGISTRATION__HEARTBEAT_INTERVAL_SECS	Heartbeat interval (seconds)
TARSUS__REGISTRATION__TOKEN	Registration token
TARSUS__RETRY__*	One key per [retry] field
TARSUS__CONSOLE__ENABLED	Enable the tokio-console endpoint
TARSUS__CONSOLE__ADDRESS	tokio-console bind address
TARSUS__CONSOLE__PORT	tokio-console port
TARSUS__TLS__ENROLLMENT_ADDRESS	CSR enrollment address (host:port)
TARSUS__TRANSPORT__ENABLED	Enable WireGuard transport
TARSUS__TRANSPORT__PRIVATE_KEY_PATH	WireGuard private key path
TARSUS__TRANSPORT__KEY_ROTATION_INTERVAL_SECS	WireGuard key rotation interval (seconds)
TARSUS__TRANSPORT__RELAY_EXPECTED_IDENTITY	Relay identity to pin
MANTIS_LOG_LEVEL	Log level, shared across Mantis services. TARSUS__LOG_LEVEL wins where both are set
MANTIS_TLS_CERT_PATH	Client TLS certificate
MANTIS_TLS_KEY_PATH	Client TLS private key
MANTIS_TLS_CA_CERT_PATH	CA certificate

See Environment Variables for complete reference.

Complete Example

Production Configuration (Listen Mode)

tarsus.toml

name = "web-server-01"
mode = "listen"
log_level = "info"

[tls]
ca_cert_path = "/etc/mantis/certs/ca.crt"

[mandible]
endpoint = "mandible.example.com:50052"

[listen]
address = "0.0.0.0"
port = 9342

[registration]
enabled = true
heartbeat_interval_secs = 30
token = "your-registration-token"

[registration.tags]
role = "web-server"
region = "us-east-1"

[retry]
retry_indefinitely = true

Production Configuration (Poll Mode)

tarsus.toml

name = "db-server-01"
mode = "poll"
log_level = "info"

[tls]
cert_path = "/etc/mantis/certs/client.crt"
key_path = "/etc/mantis/certs/client.key"
ca_cert_path = "/etc/mantis/certs/ca.crt"

[mandible]
endpoint = "mandible.example.com:50052"

[poll]
interval_secs = 15
max_commands = 5

[registration]
enabled = true

[security]
minimum_transport_level = "wireguard"

[transport]
enabled = true

Next Steps

• Mandible Configuration - REST API server
• Thorax Configuration - Orchestration server
• Environment Variables - Variable reference