Installation with Docker / Podman (Asset Mode)

XplicitTrust provides an official container image for running the agent in containerized environments such as Docker, Podman, or Kubernetes.

The container image is available at cr-public.xplicittrust.com/xtna-agent and supports amd64, arm64, and armhf architectures.

Prerequisites

The container must run with elevated network capabilities:

NET_ADMIN — required for WireGuard tunnel management and firewall rules
NET_RAW — required for raw socket operations

Rootful mode required

The container must run in rootful mode (e.g. with sudo). Rootless Docker/Podman cannot grant real network capabilities outside the user namespace.

Installation

DockerPodman

sudo docker pull cr-public.xplicittrust.com/xtna-agent:latest

sudo podman pull cr-public.xplicittrust.com/xtna-agent:latest

Configuration

See the xtna-util reference for a complete list of available flags.

The container accepts registration flags directly — no separate xtna-util step is needed.

Unattended provisioningAutomatic provisioningManual provisioning (with config file)

Use token-based registration for headless or automated deployments:

Go to the admin console settings page
Create a new "Asset Creation Token", configure it, download and store it in a secure place
Run the container with the token:

sudo docker run -d --restart unless-stopped \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  cr-public.xplicittrust.com/xtna-agent:latest \
  -token <token> -domain <tenant-domain>

Registration flags are only used on first start. Once the asset is registered, the configuration is stored inside the container and the flags are ignored on subsequent runs.

Use device flow registration for interactive setups:

sudo docker run -it --restart unless-stopped \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  cr-public.xplicittrust.com/xtna-agent:latest \
  -user <admin email address>

Open the URL shown in the terminal to authenticate. After successful registration, the container continues running in the foreground.

Go to the admin console assets page
Click Create new, fill out the form, click Apply
Click the Download Config icon at the top of the form box:
Place the configuration file in a host directory and mount it:

sudo mkdir -p /opt/xtna/my-asset
sudo cp xtna-*.xtconfig /opt/xtna/my-asset/
sudo docker run -d --restart unless-stopped \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  -v /opt/xtna/my-asset:/etc/XplicitTrust \
  cr-public.xplicittrust.com/xtna-agent:latest

Persistent Configuration (Optional)

By default, the agent stores its configuration inside the container. If the container is removed, the configuration (including certificates and registration) is lost and the asset must be re-registered.

To persist configuration across container recreation, mount a host directory:

sudo mkdir -p /opt/xtna/my-asset
sudo docker run -d --restart unless-stopped \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  -v /opt/xtna/my-asset:/etc/XplicitTrust \
  cr-public.xplicittrust.com/xtna-agent:latest \
  -token <token> -domain <tenant-domain>

Running multiple agents on one host

Each container needs its own configuration directory. Use a unique path per instance:

sudo docker run -d --name office-gw \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  -v /opt/xtna/office-gw:/etc/XplicitTrust \
  cr-public.xplicittrust.com/xtna-agent:latest \
  -token <token-1> -domain <tenant-domain>

sudo docker run -d --name lab-gw \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  -v /opt/xtna/lab-gw:/etc/XplicitTrust \
  cr-public.xplicittrust.com/xtna-agent:latest \
  -token <token-2> -domain <tenant-domain>

Registration Flags

Flag	Description
`-token <token>`	API key/token for unattended registration
`-user <email>`	Admin email for interactive device flow registration
`-domain <domain>`	Tenant domain (required with `-token`, optional with `-user`)
`-name <name>`	Asset name (defaults to container hostname)
`-api <url>`	API URL override (for on-premise deployments)

Docker Compose

services:
  xtna-agent:
    image: cr-public.xplicittrust.com/xtna-agent:latest
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
      - NET_RAW
    volumes:
      - ./xtna-config:/etc/XplicitTrust
    # Only needed on first run for registration:
    # command: ["-token", "YOUR_TOKEN", "-domain", "your-domain.com"]

Updates

The container includes a self-updating launcher that automatically updates the agent service to the latest version. No manual image pulls are required for agent updates.

To update the launcher itself, pull a new image version:

DockerPodman

sudo docker pull cr-public.xplicittrust.com/xtna-agent:latest
sudo docker restart <container-name>

sudo podman pull cr-public.xplicittrust.com/xtna-agent:latest
sudo podman restart <container-name>

Kubernetes

For Kubernetes deployments, use a DaemonSet or Deployment with the required security context:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: xtna-agent
spec:
  replicas: 1
  selector:
    matchLabels:
      app: xtna-agent
  template:
    metadata:
      labels:
        app: xtna-agent
    spec:
      containers:
        - name: xtna-agent
          image: cr-public.xplicittrust.com/xtna-agent:latest
          securityContext:
            capabilities:
              add:
                - NET_ADMIN
                - NET_RAW
          volumeMounts:
            - name: config
              mountPath: /etc/XplicitTrust
      volumes:
        - name: config
          persistentVolumeClaim:
            claimName: xtna-config

Provide the registration token via a Kubernetes Secret or environment variable in your deployment pipeline.

Troubleshooting

Container exits immediately

Ensure NET_ADMIN and NET_RAW capabilities are granted
Ensure the container runs in rootful mode (sudo)
Check logs: sudo docker logs <container-name>

"No configuration found" error

Provide registration flags (-token or -user) on first run, or mount a directory containing a valid configuration

Tunnel not working

Verify the /dev/net/tun device is available. Some container runtimes require explicit device passthrough:

sudo docker run -d \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  --device /dev/net/tun:/dev/net/tun \
  cr-public.xplicittrust.com/xtna-agent:latest

VM or container templates

When cloning a VM or container that has XplicitTrust installed, make sure to exclude /etc/XplicitTrust/ and /etc/xt-machine-id from the template. Each instance must have its own identity.