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)¶

Generate a bootstrap token in the MazeVault web UI: Settings → Deployment → Agents → Generate Bootstrap Token
Configure the agent with MAZEVAULT_SERVER_URL and MAZEVAULT_BOOTSTRAP_TOKEN
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

Re-Registration¶

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

Delete the agent from the web UI (Deployment → Agents → Delete)
Remove local state: rm -rf /etc/mazevault/agent-state.json
Generate a new bootstrap token
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)

Agents API — REST API reference for agent endpoints
FAQ — Frequently asked questions
Scaling — Agent scaling guidance
Authentication — Agent authentication details
Monitoring — Prometheus metrics for agents