Installing Defakto Agent using Docker

The Defakto Agent can be deployed using Docker Compose. This is useful when deploying the agent to a bare-metal node or VM.

To deploy the Defakto Agent, you need SSH access to the node, or the ability to write files to disk and run Docker containers.

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 an agent-config.yaml with your cluster ID and chosen attestation method. For example, using AWS Identity Document:

cluster-id: c-xxxxxx
agent-attestors:
  - type: aws_iid

Refer to the individual attestation method page for the correct type value and any required config fields. To reference the cluster by name instead of ID, use cluster-name in place of cluster-id. See Identifying the cluster.

Step 3 — Create a Docker Compose file

Create a compose.yaml:

services:
  defakto-agent:
    image: ghcr.io/spirl/defakto-agent:v0.48.2
    command: [ "/defakto-agent", "--config-file-path", "/etc/defakto/agent-config.yaml" ]
    pid: host
    volumes:
      # Make the agent's workload endpoint socket available to the host
      - type: bind
        source: /var/run/defakto
        target: /var/run/defakto
      # Make the host's Docker socket available to the agent (for Docker workload attestation)
      - type: bind
        source: /var/run/docker.sock
        target: /var/run/docker.sock
      - type: bind
        source: /etc/defakto/agent-config.yaml
        target: /etc/defakto/agent-config.yaml

Step 4 — Start the agent

docker compose up -d

Step 5 — Verify

Check that the agent container is running:

docker compose ps