Agent Setup Guide#

This guide covers the installation, registration, and configuration of CipherSwarm v2 agents.

Table of Contents#

Agent Setup Guide

Prerequisites#

System Requirements
- hashcat 6.2.6 or higher
- CUDA/OpenCL drivers (for GPU support)
- 4GB RAM minimum
- 10GB disk space
Network Requirements
- Outbound HTTPS access to CipherSwarm server
- Port 443 (HTTPS) or custom port accessible
- Stable internet connection
- Access to MinIO object storage (for resource downloads)
Administrative Access
- Administrator must register the agent via web interface
- Agent token provided during registration (shown only once)

Agent Registration (Administrator)#

Before installing an agent, an administrator must register it through the CipherSwarm web interface:

1. Web Interface Registration#

Login as Administrator
- Access the CipherSwarm web interface
- Login with administrator credentials
Navigate to Agent Management
- Go to "Agents" section
- Click "Register New Agent"

Configure Agent Details

Agent Label: GPU-Node-01
Description: Primary GPU cracking node
Project Assignment:
  - Project Alpha: ✓
  - Project Beta: ✓
  - Project Gamma: ✗

Generate Token
- Click "Create Agent"
- Copy the generated token immediately (shown only once)
- Token format: csa_<agent_id>_<random_string>

2. Project-Based Access Control#

CipherSwarm v2 introduces project-based organization:

Multi-tenancy: Agents can be assigned to multiple projects
Isolation: Agents only see tasks from assigned projects
Security: Project boundaries enforce data separation
Management: Administrators control project assignments

Installation#

1. Install Dependencies#

# Ubuntu/Debian
sudo apt update
sudo apt install -y python3.13 python3.13-venv hashcat

# RHEL/CentOS
sudo dnf install -y python3.13 hashcat

# macOS
brew install python@3.13 hashcat

# Windows
choco install python313 hashcat

2. Install CipherSwarm Agent#


# Install agent
go install github.com/unclesp1d3r/CipherSwarmAgent@latest

Configuration#

1. Basic Setup#

# Initialize agent
CipherSwarm-agent init

# Configure server connection (HTTPS required in v2)
CipherSwarm-agent config set server.url https://CipherSwarm.example.com
CipherSwarm-agent config set agent.token "csa_123_abc..."
CipherSwarm-agent config set agent.name "GPU-Node-01"

2. Authentication Configuration#

CipherSwarm v2 uses bearer token authentication:

server:
  url: https://CipherSwarm.example.com
  verify_ssl: true
  timeout: 30

authentication:
  token: csa_123_abc... # From web interface registration
  token_file: /etc/CipherSwarm/token
  token_permissions: 0600

3. Advanced Configuration#

Create agent.yaml:

server:
  url: https://CipherSwarm.example.com
  verify_ssl: true
  timeout: 30
  api_version: v1 # Agent API version

authentication:
  token: csa_123_abc...
  token_file: /etc/CipherSwarm/token
  token_permissions: 0600

agent:
  name: GPU-Node-01
  description: Primary GPU cracking node
  update_interval: 10 # Heartbeat interval (1-15 seconds)
  # HTTP resilience settings (can be overridden by server-recommended values)
  connect_timeout: 10 # seconds - TCP connection timeout
  read_timeout: 30 # seconds - API response read timeout
  write_timeout: 10 # seconds - API request write timeout
  request_timeout: 60 # seconds - overall request timeout
  api_max_retries: 3 # total attempts (1 = no retry)
  api_retry_initial_delay: 1 # seconds - first retry delay
  api_retry_max_delay: 30 # seconds - cap for exponential backoff
  circuit_breaker_failure_threshold: 5 # failures before circuit opens
  circuit_breaker_timeout: 60 # seconds - duration before half-open retry

  # Hardware capabilities (auto-detected)
  capabilities:
    gpus:
      - id: 0
        type: cuda
        name: NVIDIA GeForce RTX 4090
        memory: 24576
      - id: 1
        type: cuda
        name: NVIDIA GeForce RTX 4090
        memory: 24576
    cpu:
      cores: 16
      threads: 32
    memory: 65536

hashcat:
  binary: /usr/bin/hashcat
  workload: 3 # 1-4, higher = more GPU utilization
  temp_abort: 90 # Temperature abort threshold
  gpu_temp_retain: 80
  optimize: true

    # Backend configuration
  backend_ignore:
    cuda: false
    opencl: false
    hip: false
    metal: false

    # Device selection (1-indexed, comma-separated)
  backend_devices: 1,2 # Enable GPUs 1 and 2
    # Advanced options
  use_native_hashcat: false
  benchmark_all: false # Enable additional hash types

resources:
  cache_dir: /var/cache/CipherSwarm
  temp_dir: /tmp/CipherSwarm
  max_cache: 50GB
  cleanup_interval: 3600

    # MinIO/S3 configuration for resource downloads
  download_timeout: 300
  retry_attempts: 3

performance:
  max_tasks: 5
  min_memory: 4096
  gpu_memory_limit: 90
  cpu_limit: 80

    # Performance monitoring
  metrics_interval: 60
  device_monitoring: true

monitoring:
  interval: 60
  metrics:
    - gpu_temp
    - gpu_load
    - gpu_memory
    - cpu_load
    - memory_usage
    - hash_rate

    # Error reporting
  error_reporting: true
  log_level: INFO

security:
    # TLS/SSL (recommended for production)
  cert_file: /etc/CipherSwarm/cert.pem
  key_file: /etc/CipherSwarm/key.pem
  ca_file: /etc/CipherSwarm/ca.pem

    # Network restrictions
  allowed_ips:
    - 192.168.1.0/24
    - 10.0.0.0/8

HTTP Resilience Settings: The agent includes automatic retry logic and circuit breaker protection for network failures. These settings control timeout behavior, exponential backoff for retries, and circuit breaker activation thresholds. The server can provide recommended values via the /configuration endpoint that override local settings. For troubleshooting circuit breaker activation and network issues, see Agent Network and Connection Issues.

4. Project Context#

Agents automatically receive project assignments from the server:

Automatic Assignment: Projects are managed via web interface
Dynamic Updates: Project assignments can change without agent restart
Task Filtering: Agents only receive tasks from assigned projects
Resource Access: Only resources from assigned projects are accessible

Running the Agent#

1. Systemd Service (Recommended)#

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

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

[Service]
Type=simple
User=CipherSwarm
Group=CipherSwarm
Environment=PATH=/usr/local/bin:/usr/bin:/bin
Environment=PYTHONUNBUFFERED=1
WorkingDirectory=/var/lib/CipherSwarm
ExecStart=/usr/local/bin/CipherSwarm-agent run --config /etc/CipherSwarm/agent.yaml
Restart=always
RestartSec=5
TimeoutStopSec=30

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/CipherSwarm /var/cache/CipherSwarm /tmp/CipherSwarm

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl enable CipherSwarm-agent
sudo systemctl start CipherSwarm-agent
sudo systemctl status CipherSwarm-agent

2. Docker Container#

FROM python:3.13-slim

# Install dependencies
RUN apt-get update && apt-get install -y \
    hashcat \
    cuda-toolkit-12-0 \
    && rm -rf /var/lib/apt/lists/*

# Create user
RUN useradd -m -u 1000 CipherSwarm

# Install agent
RUN pip install CipherSwarm-agent

# Create directories
RUN mkdir -p /etc/CipherSwarm /var/lib/CipherSwarm /var/cache/CipherSwarm
RUN chown -R CipherSwarm:CipherSwarm /etc/CipherSwarm /var/lib/CipherSwarm /var/cache/CipherSwarm

# Copy configuration
COPY agent.yaml /etc/CipherSwarm/agent.yaml
COPY token /etc/CipherSwarm/token
RUN chmod 600 /etc/CipherSwarm/token
RUN chown CipherSwarm:CipherSwarm /etc/CipherSwarm/token

# Switch to non-root user
USER CipherSwarm
WORKDIR /var/lib/CipherSwarm

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD CipherSwarm-agent status || exit 1

# Run agent
CMD ["CipherSwarm-agent", "run", "--config", "/etc/CipherSwarm/agent.yaml"]

Build and run:

# Build image
docker build -t CipherSwarm-agent:v2 .

# Run container
docker run -d \
    --name CipherSwarm-agent \
    --gpus all \
    --restart unless-stopped \
    -v /etc/CipherSwarm:/etc/CipherSwarm:ro \
    -v /var/cache/CipherSwarm:/var/cache/CipherSwarm \
    -v /tmp/CipherSwarm:/tmp/CipherSwarm \
    CipherSwarm-agent:v2

3. Docker Compose#

version: '3.8'

services:
  CipherSwarm-agent:
    image: CipherSwarm-agent:v2
    container_name: CipherSwarm-agent
    restart: unless-stopped

    # GPU access
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    # Volumes
    volumes:
      - /etc/CipherSwarm:/etc/CipherSwarm:ro
      - /var/cache/CipherSwarm:/var/cache/CipherSwarm
      - /tmp/CipherSwarm:/tmp/CipherSwarm

    # Environment
    environment:
      - CUDA_VISIBLE_DEVICES=all

    # Health check
    healthcheck:
      test: [CMD, CipherSwarm-agent, status]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

    # Logging
    logging:
      driver: json-file
      options:
        max-size: 10m
        max-file: '3'

Agent Monitoring#

CipherSwarm V2 introduces enhanced agent monitoring with real-time visibility into agent health and performance.

Real-Time Status Updates#

Agent statuses are updated in real time via Turbo Streams:

Status changes (online, offline, active, error) reflect immediately in the web interface
No manual page refresh is needed
All connected users see the same live status

Agent List View#

The agent list page shows all registered agents with:

Status Badges: Color-coded indicators (green=active, gray=offline, red=error, gray=pending)
Current Task: What the agent is currently working on
Hash Rate: Live cracking speed
Error Count Badge: Number of recent errors displayed as a badge on the agent card
Last Seen: Time since the agent's last heartbeat

Hash Rate Monitoring#

Each agent displays its current and historical hash rate:

Current Rate: Live hash rate updated with each status report
Trend Indicator: Shows whether the rate is increasing, stable, or decreasing
8-Hour Chart: Performance trend chart showing hash rate over the last 8 hours

Error Badges and Notifications#

When agents encounter errors:

An error count badge appears on the agent card in the list view
Critical errors are highlighted with red indicators
Error details are accessible from the agent detail page
Errors are logged with timestamps for correlation with server events

Agent Detail Tabs#

Clicking an agent name opens the detail view with four tabs:

Overview Tab#

Agent status and uptime
Current task assignment
Hardware summary (GPU model, memory, temperature)
Performance metrics (hash rate, tasks completed, success rate)

Errors Tab#

List of recent errors with timestamps
Error severity indicators
Detailed error messages and context
Links to related tasks or attacks

Configuration Tab#

Current agent configuration settings
Heartbeat interval
Workload settings
Backend device selection
Project assignments

Capabilities Tab#

Detected hardware (GPUs, CPUs)
Supported backends (CUDA, OpenCL, HIP, Metal)
Benchmark results by hash type
Device memory and temperature thresholds

Performance Charts (8-Hour Trends)#

The agent detail page includes performance trend charts:

Hash Rate Over Time: Line chart showing cracking speed over 8 hours
GPU Temperature: Temperature readings correlated with workload
GPU Utilization: Percentage utilization over time
Task Throughput: Tasks completed per hour

These charts help identify:

Performance degradation due to thermal throttling
Inconsistent workloads or idle periods
Optimal operating conditions for each agent

Agent Management via Web Interface#

1. Agent Status Monitoring#

Administrators can monitor agents through the web interface:

Real-time Status: Online/offline, current tasks, performance
Hardware Information: GPU temperatures, utilization, memory usage
Performance Metrics: Hash rates, task completion times
Error Logs: Agent errors and warnings

2. Configuration Management#

Basic Settings#

Enable/Disable: Toggle agent availability
Update Interval: Heartbeat frequency (1-15 seconds)
Project Assignment: Multi-project access control

Hardware Configuration#

Device Toggles: Enable/disable individual GPUs/CPUs
Backend Selection: CUDA, OpenCL, HIP, Metal
Temperature Limits: Abort thresholds (default 90°C)
Workload Settings: GPU utilization levels (1-4)

Advanced Options#

Native Hashcat: Use system hashcat instead of bundled version
Additional Hash Types: Enable --benchmark-all for more hash types
Custom Configurations: Advanced hashcat parameters

3. Performance Monitoring#

Live Charts: 8-hour performance trends
Device Utilization: Per-GPU utilization percentages
Benchmark Results: Hash type performance data
Task History: Completed and failed task statistics

Monitoring and Diagnostics#

1. Log Files#

# Service logs
journalctl -u CipherSwarm-agent -f

# Agent logs
tail -f /var/log/CipherSwarm/agent.log

# Docker logs
docker logs -f CipherSwarm-agent

2. Agent Status Commands#

# Check agent status
CipherSwarm-agent status

# Test server connection
CipherSwarm-agent test connection

# Verify authentication
CipherSwarm-agent test auth

# Hardware diagnostics
CipherSwarm-agent diagnostics

# Benchmark performance
CipherSwarm-agent benchmark

3. Performance Metrics#

The agent exposes metrics for monitoring:

# Agent status
cipherswarm_agent_status{state="active"} 1

# Task metrics
cipherswarm_agent_tasks_total{status="completed"} 150
cipherswarm_agent_tasks_total{status="failed"} 5

# Hardware metrics
cipherswarm_agent_gpu_temperature{gpu="0"} 75.5
cipherswarm_agent_gpu_utilization{gpu="0"} 85.2
cipherswarm_agent_hash_rate{gpu="0"} 1250000

Troubleshooting#

1. Authentication Issues#

# Check token validity
CipherSwarm-agent test auth

# Verify token format
echo $CIPHERSWARM_TOKEN | grep -E '^csa_[0-9]+_[a-zA-Z0-9]+$'

# Test server connectivity
curl -H "Authorization: Bearer $CIPHERSWARM_TOKEN" \
    https://CipherSwarm.example.com/api/v1/client/configuration

2. Project Access Issues#

Verify Project Assignment: Check web interface for agent's project assignments
Contact Administrator: Request access to required projects
Check Logs: Look for project-related error messages

3. Performance Issues#

# Check GPU status
nvidia-smi

# Test hashcat directly
hashcat --benchmark --machine-readable

# Monitor system resources
htop
iotop

4. Common Problems#

Agent Not Appearing in Web Interface
- Verify token is correct and not expired
- Check network connectivity to server
- Ensure HTTPS is properly configured
- Review agent logs for authentication errors
No Tasks Assigned
- Verify agent is assigned to projects with active campaigns
- Check agent is enabled in web interface
- Ensure agent meets task requirements (GPU memory, etc.)
High Resource Usage
- Adjust workload settings (reduce from 4 to 3 or 2)
- Check thermal throttling with nvidia-smi
- Reduce concurrent tasks in configuration
- Monitor system memory usage
Connection Timeouts
- Verify firewall rules allow HTTPS traffic
- Check DNS resolution for server hostname
- Test with curl or wget to verify connectivity
- Review proxy settings if applicable
GPU Not Detected
- Update GPU drivers to latest version
- Verify CUDA installation: nvidia-smi
- Check hashcat GPU detection: hashcat -I
- Ensure user has GPU access permissions
Network Connection Issues

If agent logs show "circuit breaker open" messages, this indicates the agent is protecting against repeated server connection failures. The circuit breaker automatically attempts recovery after 60 seconds by default. See Circuit Breaker Recovery for details. No agent restart is needed.

Maintenance#

1. Updates#

# Update agent software
pip install --upgrade CipherSwarm-agent

# Update configuration
CipherSwarm-agent config update

# Restart service
sudo systemctl restart CipherSwarm-agent

# Verify update
CipherSwarm-agent --version

2. Token Rotation#

When tokens need to be rotated:

Administrator: Generate new token via web interface
Agent: Update configuration with new token
Restart: Restart agent service
Verify: Check agent appears online in web interface

3. Backup and Recovery#

# Backup configuration
cp /etc/CipherSwarm/agent.yaml /etc/CipherSwarm/agent.yaml.bak
cp /etc/CipherSwarm/token /etc/CipherSwarm/token.bak

# Backup cache (optional)
tar -czf CipherSwarm-cache-backup.tar.gz /var/cache/CipherSwarm

# Recovery
cp /etc/CipherSwarm/agent.yaml.bak /etc/CipherSwarm/agent.yaml
cp /etc/CipherSwarm/token.bak /etc/CipherSwarm/token
sudo systemctl restart CipherSwarm-agent

4. Cleanup#

# Clear cache
CipherSwarm-agent cleanup cache

# Remove temporary files
CipherSwarm-agent cleanup temp

# Reset agent (removes all local data)
CipherSwarm-agent reset --confirm

Security Best Practices#

1. Token Security#

Secure Storage: Store tokens in files with 600 permissions
Environment Variables: Use environment variables for containers
Regular Rotation: Rotate tokens periodically
Access Control: Limit who can access token files

2. Network Security#

HTTPS Only: Always use HTTPS for server communication
Certificate Validation: Verify SSL certificates
Firewall Rules: Restrict outbound connections to necessary ports
VPN/Private Networks: Use private networks when possible

3. System Security#

Non-root User: Run agent as dedicated non-root user
File Permissions: Restrict access to configuration files
System Updates: Keep system and dependencies updated
Monitoring: Monitor for suspicious activity

4. Container Security#

Non-root Container: Use non-root user in containers
Read-only Filesystem: Mount configuration as read-only
Resource Limits: Set appropriate CPU/memory limits
Security Scanning: Regularly scan container images

Performance Optimization#

1. Hardware Optimization#

GPU Selection: Use high-end GPUs for better performance
Memory: Ensure sufficient system RAM (16GB+ recommended)
Storage: Use SSD for cache and temporary files
Cooling: Maintain proper cooling for sustained performance

2. Configuration Tuning#

# High-performance configuration
hashcat:
  workload: 4 # Maximum GPU utilization
  optimize: true

performance:
  max_tasks: 3 # Reduce for stability
  gpu_memory_limit: 95 # Use more GPU memory
resources:
  max_cache: 100GB # Larger cache for better performance

3. Monitoring and Tuning#

Temperature Monitoring: Keep GPUs below 80°C for optimal performance
Utilization Tracking: Aim for 90%+ GPU utilization
Memory Usage: Monitor system and GPU memory usage
Task Completion: Track task completion rates and adjust settings

For additional information:

Web Interface Guide - Managing agents via web interface
Attack Configuration - Understanding attack types
Troubleshooting Guide - Common issues and solutions
Agent Troubleshooting - Detailed agent diagnostics and task lifecycle
API Documentation - Agent API reference