warning

The binaries used for Linux packages are dynamically linked and require glibc >=2.17 to be present on the system.

Installing Defakto Agent on Linux

The Defakto Agent can be deployed on Linux systems to issue SPIFFE IDs to workloads running on a bare-metal node or VM.

To deploy the Defakto Agent, you need either SSH access to the node, or the ability to write files to disk, download files from a URL, and install a package. You should also have systemd running on the node.

Step 1 — Choose an agent attestation method

The agent must authenticate to the Trust Domain Server using an attestation method. Choose the method that matches your environment:

• Cloud-hosted VMs — Consider using the cloud provider's identity mechanism, such as AWS Identity Document, Azure IMDS, or GCP Instance Identity Token. These require no pre-distributed secrets.
• On-premises or non-cloud environments — Consider methods such as SSH Proof of Possession, TPM Endorsement Key, or X.509 Proof of Possession.

See Agent Attestation Methods for the full list of available methods, policy configuration, and server-side setup.

Step 2 — Create the agent configuration

Create /etc/spirl/agent-config.yaml with your Trust Domain Server endpoint used during deployment and chosen attestation method. For example, using AWS Identity Document:

spirl-endpoint: your-trust-domain.org:443
agent-attestors:
  - type: aws_iid

Refer to the individual attestation method page for the correct type value and any required config fields.

For all available configuration keys, see the Configuration Reference below.

Step 3 — Install the agent

Download the package for your architecture:

# AMD64 Debian
curl -o spirl-agent.deb https://spirl-releases.s3.us-west-2.amazonaws.com/spirl-agent/0.41.0/spirl-agent_0.41.0_linux_amd64.deb

# AMD64 RPM
curl -o spirl-agent.rpm https://spirl-releases.s3.us-west-2.amazonaws.com/spirl-agent/0.41.0/spirl-agent_0.41.0_linux_amd64.rpm

# ARM64 Debian
curl -o spirl-agent.deb https://spirl-releases.s3.us-west-2.amazonaws.com/spirl-agent/0.41.0/spirl-agent_0.41.0_linux_arm64.deb

# ARM64 RPM
curl -o spirl-agent.rpm https://spirl-releases.s3.us-west-2.amazonaws.com/spirl-agent/0.41.0/spirl-agent_0.41.0_linux_arm64.rpm

Install the Debian package:

sudo dpkg -i spirl-agent.deb

Or the RPM package:

sudo yum install spirl-agent.rpm

Step 4 — Verify

Verify the service is running:

systemctl status spirl-agent.service

Configuration Reference

The agent is configured via a YAML file at /etc/spirl/agent-config.yaml. The file path can be overridden with the --config-file-path flag or SPIRL_CONFIG_FILE_PATH env var. Keys use kebab-case.

Required

Key	Type	Default	Description
spirl-endpoint	string or []string	localhost:8180	Address(es) of the Trust Domain Server endpoint

Agent attestation configuration is also required — see Agent Attestation below.

Connection to TD Server

Key	Type	Default	Description
spirl-endpoint-enable-tls	bool	true	Use TLS when connecting to the Trust Domain Server endpoint
spirl-endpoint-supplemental-roots-file	string	""	Supplemental root CAs for validating the Trust Domain Server endpoint
spirl-endpoint-connection-max-age	duration	30m	Max age of connections to the Trust Domain Server endpoint

Workload Attestation

Fields marked with * can also be set via Managed Configuration, which is the preferred approach. Values set here override the managed configuration.

Key	Type	Default	Description
spiffe-socket-path	string	/var/run/spirl/spiffe.sock	Path to the SPIFFE Workload API socket
disable-kubernetes-attestation *	bool	false	Turn off Kubernetes workload attestation
disable-docker-attestation *	bool	true	Turn off Docker workload attestation
linux-attestation-discover-workload-path *	bool	false	Enable discovery of workload binary path during attestation
jwt-attestation-supplemental-roots-file	string	""	Additional root CAs in PEM format for JWKS URL validation
extension-workload-attestation-exec-cmd	string	""	Path to the extension workload attestor executable
extension-workload-attestation-exec-args	[]string	[]	Arguments to pass to the extension workload attestor
extension-workload-attestation-exec-checksum	string	""	SHA256 checksum of the extension executable for integrity verification
extension-workload-attestation-timeout	duration	100ms	Timeout for the extension workload attestor to complete
allowed-attributes *	[]string	[]	Attribute filter patterns; attributes not matching at least one filter are redacted
supplemental-roots-file	string	""	CAs to inject into the local trust bundle served to workloads via the SPIFFE Workload API, in addition to the Defakto-issued bundle

Agent Attestation

Key	Type	Default	Description
agent-attestation-method	string	""	Method for attesting the agent to the server
agent-attestors	Array of { type: string, config: object }	[]	Agent attestor configurations
cluster-version-id	string	""	Cluster version ID used to authenticate the agent to the Trust Domain Server
cluster-version-key-file	string	""	Path to the cluster version private key file

See Agent Attestation Methods for the full list of attestation methods and their configuration.

Telemetry & Observability

Key	Type	Default	Description
spirl-agent-id	string	""	Human-readable agent identifier shown in logs and dashboards. If unset, a random ID is generated at startup (and changes on each restart).
telemetry-metrics-api-listen-addr	string	""	Address for Prometheus metrics endpoints
telemetry-enable-grpc-latency-monitoring	bool	false	Enable gRPC latency histogram metrics
telemetry-enable-workload-svid-expiry-metrics	bool	false	Enable workload SVID expiry metrics with pod/namespace/service-account labels
health-listen-addr	string	:8086	Address for /ready and /live health endpoints; set to "" to disable
silence-usage-logs	bool	false	Suppress CPU/memory resource limit logging