Deploy the Spire Agent

Kubernetes

Helm (Recommended)

1.1 Clone the Helm chart repository

git clone https://github.com/authsec-ai/spire-agent.git

1.2 Install with your Tenant ID

helm install spire-agent ./spire-agent/charts/spire-agent \
  --namespace spire \
  --create-namespace \
  --set tenantId="YOUR-TENANT-UUID"

That's it. The chart creates the namespace, service account, RBAC, ConfigMap, and DaemonSet automatically.

For multi-cluster setups, also set the cluster name:

helm install spire-agent ./spire-agent/charts/spire-agent \
  --namespace spire \
  --create-namespace \
  --set tenantId="YOUR-TENANT-UUID" \
  --set clusterName="customer-prod-east-1"

1.3 (Optional) Customize with a values file

For production tuning, create a values.yaml override:

tenantId: "YOUR-TENANT-UUID"
clusterName: "customer-prod-east-1"

image:
  repository: docker-repo-public.authsec.ai/spire-agent
  tag: "latest"

resources:
  requests:
    memory: "256Mi"
    cpu: "200m"
  limits:
    memory: "512Mi"
    cpu: "500m"

logging:
  level: "info"    # debug, info, warn, error

nodeSelector: {}   # e.g. { role: worker } to target specific nodes

Then install with:

helm install spire-agent ./spire-agent/charts/spire-agent \
  --namespace spire \
  --create-namespace \
  -f values.yaml

Helm Values Reference

Value	Default	Description
tenantId	"" (required)	Your tenant UUID from AuthSec
clusterName	"production"	Cluster identifier for multi-cluster setups
image.repository	docker-repo-public.authsec.ai/spire-agent	Agent container image
image.tag	"latest"	Image tag
resources.requests.memory	256Mi	Memory request
resources.limits.memory	512Mi	Memory limit
logging.level	"info"	Log level
health.port	8080	Health check port
nodeSelector	{}	Target specific nodes
tolerations	NoSchedule + NoExecute	Node tolerations
rbac.create	true	Create ClusterRole and binding
serviceAccount.create	true	Create service account

Raw Manifests

If you are not using Helm, download and apply the static manifest:

1.1 Download the manifest

curl -fsSLO https://raw.githubusercontent.com/authsec-ai/spire-agent/main/manifests/spire-agent-daemonset.yaml

1.2 Edit the ConfigMap

Open spire-agent-daemonset.yaml and set your Tenant ID:

apiVersion: v1
kind: ConfigMap
metadata:
  name: spire-agent-config
  namespace: spire
data:
  config.yaml: |
    agent:
      tenant_id: "YOUR-TENANT-UUID"        # <-- Set this
      # ...
    attestation:
      kubernetes:
        cluster_name: "YOUR-CLUSTER-NAME"   # <-- Set this (optional)

1.3 Apply

kubectl apply -f spire-agent-daemonset.yaml

This creates the spire namespace, service account, RBAC, ConfigMap, and DaemonSet in one step.

Verify

# One Running pod per node
kubectl get pods -n spire -l app=spire-agent

# Check logs — look for "Agent SVID renewal successful"
kubectl logs -n spire -l app=spire-agent --tail=20

Expected output:

{"event": "Agent startup completed successfully", ...}
{"event": "Agent SVID renewal successful", "spiffe_id": "spiffe://YOUR-TENANT-UUID/agent/...", "ttl": 3600, ...}
{"event": "gRPC Workload API Server started", ...}

Upgrade or uninstall

# Pull latest chart changes
cd spire-agent && git pull && cd ..

# Upgrade (e.g. new image tag)
helm upgrade spire-agent ./spire-agent/charts/spire-agent \
  --namespace spire \
  --set tenantId="YOUR-TENANT-UUID" \
  --set image.tag="1.2.0"

# Uninstall
helm uninstall spire-agent --namespace spire

Docker

1.1 Create a docker-compose.yml

version: '3.8'

services:
  spire-agent:
    image: docker-repo-public.authsec.ai/spire-agent:latest
    container_name: spire-agent
    restart: unless-stopped

    environment:
      - ICP_AGENT_AGENT__TENANT_ID=YOUR-TENANT-UUID
      - ICP_AGENT_AGENT__NODE_ID=docker-host-01
      - ICP_AGENT_ATTESTATION__TYPE=docker
      - ICP_AGENT_LOGGING__LEVEL=info

    volumes:
      # Shared socket — your workloads mount this to get SVIDs
      - spire-socket:/run/spire/sockets

      # Docker socket — required for container attestation
      - /var/run/docker.sock:/var/run/docker.sock:ro

    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8080/health')"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

volumes:
  spire-socket:
    driver: local

1.2 Start the agent

docker compose up -d

1.3 View real-time logs

# Follow logs in real time
docker compose logs spire-agent -f

# Filter for errors
docker compose logs spire-agent -f 2>&1 | grep -i error

# Pretty-print JSON logs (requires jq)
docker compose logs spire-agent -f --no-log-prefix 2>&1 | jq .

1.4 Add workloads to the same compose file

Your application containers need to mount the shared socket volume:

services:
  spire-agent:
    # ... (as above)

  my-ai-agent:
    build: ./my-agent
    container_name: my-ai-agent
    depends_on:
      spire-agent:
        condition: service_healthy
    environment:
      - SPIFFE_ENDPOINT_SOCKET=/run/spire/sockets/agent.sock
    volumes:
      - spire-socket:/run/spire/sockets:ro
    labels:
      - "app=my-ai-agent"
      - "env=production"

volumes:
  spire-socket:
    driver: local

Key points:

• Your workload mounts spire-socket as read-only
• The labels on your container are used for attestation (they must match the workload entry selectors)
• depends_on with service_healthy ensures the agent is ready before your workload starts

Verify

# Check agent is running and healthy
docker compose ps
docker compose logs spire-agent --tail=20

# Expected:
# {"event": "Agent startup completed successfully", ...}
# {"event": "gRPC Workload API Server started", ...}

Upgrade or uninstall

# Pull latest image and restart
docker compose pull spire-agent
docker compose up -d spire-agent

# Stop and remove
docker compose down

Unix (VM / Bare Metal)

1.1 Install the agent

git clone https://github.com/authsec-ai/spire-agent.git
cd spire-agent
sudo bash unix/install.sh

The installer will prompt for your Tenant ID, then automatically:

• Create a spire-agent system user
• Install the binary to /usr/local/bin/spire-agent
• Set up directories (/etc/spire-agent, /var/lib/spire-agent, /run/spire/sockets, /var/log/spire-agent)
• Copy the default config and systemd service
• Set the node ID to the system hostname

For automated/scripted installs, pass the Tenant ID as an environment variable:

sudo TENANT_ID="YOUR-TENANT-UUID" bash unix/install.sh

1.2 Start the agent

sudo systemctl start spire-agent

1.3 View real-time logs

The agent writes structured JSON logs:

# Follow systemd logs in real time
sudo journalctl -u spire-agent -f

# Filter for errors only
sudo journalctl -u spire-agent -f --grep="ERROR"

# Pretty-print JSON logs in real time (requires jq)
sudo journalctl -u spire-agent -f -o cat | jq .

# Follow the log file directly
tail -f /var/log/spire-agent/agent.log

# Filter specific events (e.g. SVID renewals)
sudo journalctl -u spire-agent -f -o cat | jq 'select(.event | test("renewal|SVID"))'

1.4 Set socket permissions

Your application process needs read access to the socket:

# Option A: run your app as the same user
sudo chmod 755 /run/spire/sockets

# Option B: add your app user to a shared group
sudo chgrp myapp-group /run/spire/sockets/agent.sock
sudo chmod 660 /run/spire/sockets/agent.sock

Verify

# Check agent is running
sudo systemctl status spire-agent

# Check socket exists
ls -la /run/spire/sockets/agent.sock

# Check health
curl -s http://localhost:8080/health

Expected output:

{"status": "healthy"}

For detailed component status:

curl -s http://localhost:8080/status | jq .

{
  "status": "healthy",
  "ready": true,
  "components": {
    "agent_svid": { "status": "healthy" },
    "icp_service": { "status": "healthy" },
    "certificate_cache": { "status": "healthy" },
    "workload_api": { "status": "healthy" }
  }
}

Upgrade or uninstall

# Upgrade — pull the latest binary and reinstall
cd spire-agent && git pull
sudo bash unix/uninstall.sh
sudo bash unix/install.sh

# Uninstall (keeps config and data)
sudo bash unix/uninstall.sh

# Uninstall and remove everything
sudo bash unix/uninstall.sh --purge