Tarsus Configuration

Tarsus Configuration

Configure the Tarsus client agent.

Configuration File

Tarsus searches for a config file in the following order:

1. Path specified by TARSUS_CONFIG environment variable
2. tarsus.toml in the current directory
3. /etc/mantis/client.toml
4. ~/.config/mantis/client.toml (platform-dependent config directory)

If no file is found, defaults are used. Environment variables always override file settings.

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"
trust_server_thumbprint = "a1b2c3d4..."

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
server_name	string	-	No	Server name for SNI validation
trust_server_thumbprint	string	-	Yes (thumbprint mode)	Expected server certificate SHA-256 thumbprint (64 hex chars). Required when using auto-generated certs. Env: MANTIS_TLS_SERVER_THUMBPRINT

Note

When cert_path and key_path are not set, Tarsus auto-generates a self-signed certificate. In this mode, trust_server_thumbprint is required for mutual trust verification (thumbprint mode).

When cert_path and key_path are set (CA-signed mode), trust_server_thumbprint is optional since trust is established via the CA chain.

[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

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

[registration]

Registration and heartbeat configuration.

[registration]
enabled = true
heartbeat_interval_secs = 30
max_retries = 3
retry_delay_secs = 5
environment = "production"
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
max_retries	integer	3	No	Max registration retry attempts
retry_delay_secs	integer	5	No	Delay between retries (seconds)
environment	string	-	No	Environment name for auto-created target (e.g., "production"). Env: TARSUS__REGISTRATION__ENVIRONMENT
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

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	true (no config file); false (serde default when section is absent)	No	Enable the tokio-console server. When Tarsus starts without a config file it uses ConsoleConfig::with_port(6671), which sets enabled = true. When a config file is present but omits [console], serde’s own default applies (enabled = false, port 0). Env: TARSUS__CONSOLE__ENABLED
address	string	"127.0.0.1"	No	Bind address. Env: TARSUS__CONSOLE__ADDRESS
port	integer	6671 (assigned at startup)	No	Console port (Tarsus assigns 6671 at startup; the serde default is the sentinel 0). 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

[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", attempts to disable WireGuard transport via the TARSUS__TRANSPORT__ENABLED environment variable are blocked and a security audit warning is logged. This prevents attackers with access to environment variables from downgrading transport security.

Environment Variables

Tarsus uses double-underscore env var names in its apply_env_overrides() method.

Environment Variable	Description
TARSUS_CONFIG	Path to config file
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__LISTEN__ADDRESS	Listen bind address
TARSUS__LISTEN__PORT	Listen port
TARSUS__POLL__INTERVAL_SECS	Poll interval (seconds)
TARSUS__REGISTRATION__HEARTBEAT_INTERVAL_SECS	Heartbeat interval (seconds)
TARSUS__REGISTRATION__ENVIRONMENT	Environment name for target
TARSUS__REGISTRATION__TOKEN	Registration token
MANTIS_TLS_CERT_PATH	Client TLS certificate
MANTIS_TLS_KEY_PATH	Client TLS private key
MANTIS_TLS_CA_CERT_PATH	CA certificate
MANTIS_TLS_SERVER_THUMBPRINT	Server thumbprint (SHA-256 hex)
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)

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"
trust_server_thumbprint = "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"

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

[listen]
address = "0.0.0.0"
port = 9342

[registration]
enabled = true
heartbeat_interval_secs = 30
environment = "production"
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
environment = "production"

[security]
minimum_transport_level = "wireguard"

[transport]
enabled = true

Next Steps

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