Skip to content

Agent Deployment Guide

Installation, Configuration, and Operation of MazeVault Agents

Document Version: 1.0.0
Last Updated: 2026-04-03

1. Overview

The MazeVault Agent is a lightweight Go binary deployed on infrastructure nodes. It provides:

  • Secret synchronization — Automatic delivery of secrets to local applications
  • Certificate discovery — Scanning infrastructure for certificates (filesystem, JKS, Windows cert store)
  • Certificate lifecycle — Automated renewal and deployment of managed certificates
  • Real-time updates — WebSocket connection for instant push notifications
  • Local proxy — Secure proxy for application access to secrets without direct API calls
  • Offline resilience — Local caching ensures operation during network interruptions

2. Supported Platforms

Platform Architecture Notes
Linux x86_64, ARM64 Ubuntu, RHEL, Rocky Linux, Debian, Alpine
Windows x86_64 Windows Server 2019+
Kubernetes Any Sidecar container or DaemonSet

3. Installation

3.1 Linux — Binary Installation

# Download the agent binary
curl -sL https://vault.example.com/api/v1/agents/download/linux-amd64 -o mazevault-agent
chmod +x mazevault-agent
sudo mv mazevault-agent /usr/local/bin/

# Create configuration directory
sudo mkdir -p /etc/mazevault
sudo mkdir -p /var/lib/mazevault/certs

3.2 Linux — systemd Service

Create /etc/systemd/system/mazevault-agent.service:

[Unit]
Description=MazeVault Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
EnvironmentFile=/etc/mazevault/agent.env
ExecStart=/usr/local/bin/mazevault-agent
Restart=always
RestartSec=10
User=mazevault
Group=mazevault

[Install]
WantedBy=multi-user.target

# Create service user
sudo useradd -r -s /sbin/nologin mazevault

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable mazevault-agent
sudo systemctl start mazevault-agent

3.3 Kubernetes — Sidecar Container

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  template:
    spec:
      containers:
        - name: app
          image: my-app:latest
          volumeMounts:
            - name: secrets
              mountPath: /var/run/secrets/mazevault
        - name: mazevault-agent
          image: ghcr.io/mazevault/agent:latest
          env:
            - name: MAZEVAULT_SERVER_URL
              value: "https://vault.example.com"
            - name: MAZEVAULT_BOOTSTRAP_TOKEN
              valueFrom:
                secretKeyRef:
                  name: mazevault-bootstrap
                  key: token
          volumeMounts:
            - name: secrets
              mountPath: /var/run/secrets/mazevault
      volumes:
        - name: secrets
          emptyDir:
            medium: Memory

3.4 Kubernetes — DaemonSet

For cluster-wide certificate discovery and management:

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: mazevault-agent
  namespace: mazevault
spec:
  selector:
    matchLabels:
      app: mazevault-agent
  template:
    metadata:
      labels:
        app: mazevault-agent
    spec:
      serviceAccountName: mazevault-agent
      containers:
        - name: agent
          image: ghcr.io/mazevault/agent:latest
          env:
            - name: MAZEVAULT_SERVER_URL
              value: "https://vault.example.com"
            - name: MAZEVAULT_BOOTSTRAP_TOKEN
              valueFrom:
                secretKeyRef:
                  name: mazevault-bootstrap
                  key: token
          resources:
            requests:
              cpu: 50m
              memory: 64Mi
            limits:
              cpu: 200m
              memory: 128Mi

4. Configuration

4.1 Environment Variables

Create /etc/mazevault/agent.env:

# Required
MAZEVAULT_SERVER_URL=https://vault.example.com
MAZEVAULT_BOOTSTRAP_TOKEN=mvbt_xxxxxxxxxxxxx

# Optional — Agent Identity
MAZEVAULT_AGENT_NAME=app-server-01
MAZEVAULT_PROJECT_ID=proj_xxxxxxxxxxxxx

# Optional — Storage
MAZEVAULT_CERT_STORE_PATH=/var/lib/mazevault/certs
MAZEVAULT_STATE_DIR=/etc/mazevault

# Optional — Logging
MAZEVAULT_LOG_LEVEL=info        # debug, info, warn, error
MAZEVAULT_LOG_FORMAT=text       # text, json

# Optional — Sync
SYNC_INTERVAL_SECONDS=300       # Default: 300 (5 minutes)

4.2 Variable Reference

Variable Required Default Description
MAZEVAULT_SERVER_URL Yes — MazeVault backend URL
MAZEVAULT_BOOTSTRAP_TOKEN Yes ¹ — One-time registration token
MAZEVAULT_AGENT_NAME No hostname Display name in UI
MAZEVAULT_PROJECT_ID No — Project scope for secrets
MAZEVAULT_CERT_STORE_PATH No /var/lib/mazevault/certs Certificate storage directory
MAZEVAULT_STATE_DIR No /etc/mazevault Configuration and state directory
MAZEVAULT_LOG_LEVEL No info Log verbosity
MAZEVAULT_LOG_FORMAT No text Log format (text or json)
SYNC_INTERVAL_SECONDS No 300 Secret sync interval in seconds

¹ Required only for initial registration. After bootstrap, the agent uses mTLS certificates.

5. Bootstrap & Registration

The agent uses a two-phase authentication model:

Phase 1: Bootstrap (One-Time)

  1. Generate a bootstrap token in the MazeVault web UI: Settings → Deployment → Agents → Generate Bootstrap Token
  2. Configure the agent with MAZEVAULT_SERVER_URL and MAZEVAULT_BOOTSTRAP_TOKEN
  3. Start the agent — it registers automatically via POST /api/v1/agents/register

Phase 2: mTLS (Ongoing)

After successful registration, the agent receives:

  • Client certificate — For mutual TLS authentication
  • CA certificate — For verifying the server
  • Heartbeat interval — Recommended reporting frequency
  • Sync interval — Secret synchronization frequency

All subsequent communication uses mTLS. The bootstrap token is no longer needed and can be revoked.

┌──────────┐          ┌───────────────┐
│  Agent   │──────────│  MazeVault    │
│          │ Bootstrap│  Backend      │
│          │  Token   │               │
│          │◀─────────│               │
│          │ mTLS Cert│               │
│          │          │               │
│          │──────────│               │
│          │ mTLS     │               │
│          │ (ongoing)│               │
└──────────┘          └───────────────┘

6. Periodic Operations

The agent runs several background tasks automatically:

Operation Interval Description
Secret sync Configurable (default 5m) Synchronizes secrets from backend to local storage
Heartbeat 60 seconds Reports health, metrics (CPU, memory, disk), and version to backend
Certificate discovery 1 hour Scans configured paths for certificates (filesystem, JKS, Windows cert store)
Update check 24 hours Checks for newer agent versions
License heartbeat 5 minutes Sends telemetry to license server (when configured)
K8s reconciliation 5 minutes Reconciles Kubernetes Secret certificates (K8s only)
WebSocket reconnect Exponential backoff Maintains real-time push connection (1s → 2s → 4s → ...)

All intervals are fixed except secret sync (SYNC_INTERVAL_SECONDS).

7. Certificate Discovery

The agent discovers certificates across infrastructure and reports them to the backend:

Discovery Sources

Source Platform Description
Filesystem Linux/Windows Scans configured directories for PEM, DER, PFX files
Java KeyStore (JKS) All Parses .jks and .p12 files
Windows Certificate Store Windows Enumerates system and user certificate stores
Kubernetes Secrets K8s Watches kubernetes.io/tls secrets

Discovery Configuration

Discovery paths are configured via the MazeVault web UI under:

Project → Settings → Agent Discovery → Paths

Results appear in the Discovered Certificates view in the dashboard.

8. Monitoring

Health Endpoint

The agent reports health via heartbeat. Monitor agent status in the web UI:

Deployment → Agents

Key Metrics Reported

  • cpu_percent — Agent CPU usage
  • memory_percent — Agent memory usage
  • secrets_synced — Number of secrets synchronized
  • certificates_managed — Number of managed certificates
  • last_sync_time — Timestamp of last successful sync
  • uptime_seconds — Agent uptime

Prometheus Metrics

The backend exposes agent metrics at /metrics:

mazevault_agents_online{environment="production"} 12
mazevault_agent_sync_operations_total{agent_id="agt_xyz"} 1842
mazevault_agent_discovery_findings_total{agent_id="agt_xyz"} 37

9. Troubleshooting

Agent Won't Start

# Check logs
journalctl -u mazevault-agent -f

# Verify connectivity
curl -sk https://vault.example.com/api/v1/health
Problem Cause Solution
connection refused Backend unreachable Verify MAZEVAULT_SERVER_URL and firewall rules
certificate expired Agent cert expired Re-register with new bootstrap token
bootstrap token invalid Token expired or used Generate a new bootstrap token in the web UI
TLS handshake error CA certificate mismatch Verify CA certificate chain

Agent Lifecycle (Deployment → Agents)

Registered agents are managed from Deployment → Agents via the per-row actions menu. These operations act on the MazeVault control-plane identity of an installed agent and are distinct from deleting a generated install-script record under Deployment → Deploy.

Action What it does When to use
Unregister (Odregistrovat) Retires the agent, invalidates its mTLS identity and recovery tokens, deactivates project bindings, and blocks all future runtime use. History is preserved. Choose a security reason category (compromised / lost credential / stolen host) to record it as a revoke. Decommissioned, lost, offline, or manually removed hosts.
Remote uninstall (Odinstalovat vzdáleně) Asks a connected agent to uninstall itself from the host and reports the real outcome back before finalizing. Supported on Linux (systemd package install, agent running as root) and Windows (MSI service install; the MazeVaultAgent service is removed via msiexec). The agent must be currently connected. The agent is retired only after it confirms a successful removal; if the removal fails the agent stays active and the console shows Uninstall failed so you can retry or intervene. Cleanly remove the agent from a reachable Linux or Windows host.
Re-register / Renew identity (Přeregistrovat) Retires the old identity and issues a single-use replacement bootstrap token (valid 24 h) for re-enrolling the host. mTLS certificate expired or compromised; replacing a host.

An impact preview (managed certificates, project bindings, rotation targets, SSH keys, pending keytab work) is shown before unregistering. Unresolved work such as pending keytab deployments or actively managed certificates requires the Force option to proceed.

Unregister does not uninstall the host binary. For offline hosts, or where remote uninstall is unsupported (non-packaged/manual installs, macOS), unregister the agent and remove it locally.

Linux:

sudo systemctl stop mazevault-agent && sudo systemctl disable mazevault-agent
sudo apt remove mazevault-agent   # or: sudo rpm -e mazevault-agent
sudo rm -rf /etc/mazevault /var/lib/mazevault /var/log/mazevault

Windows (PowerShell, elevated):

sc.exe stop MazeVaultAgent
$p = Get-WmiObject Win32_Product -Filter "Name='MazeVault Agent'"
if ($p) { $p.Uninstall() } else { sc.exe delete MazeVaultAgent }
Remove-Item -Recurse -Force "$env:ProgramData\MazeVault" -ErrorAction SilentlyContinue

Re-Registration

If the agent's mTLS certificate expires or is compromised:

  1. In Deployment → Agents, open the agent's actions menu and choose Re-register / Renew identity (or Unregister with a security reason for a compromised host).
  2. Copy the single-use replacement bootstrap token from the dialog.
  3. Remove local state on the host: rm -rf /etc/mazevault/agent-state.json
  4. Restart the agent with the new MAZEVAULT_BOOTSTRAP_TOKEN.

Debug Logging

Enable verbose logging for diagnostics:

MAZEVAULT_LOG_LEVEL=debug mazevault-agent

10. Security Considerations

  • Bootstrap tokens are single-use and time-limited (default: 24 hours)
  • mTLS certificates are scoped to the specific agent and project
  • Secret data is encrypted in transit (TLS 1.2+) and cached encrypted locally
  • Minimal permissions — agents only access secrets assigned to their project
  • No inbound ports — the agent initiates all connections (outbound only)