Agent Setup Guide#

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

Table of Contents#

• Agent Setup Guide
  • Table of Contents
  • Prerequisites
  • Agent Registration (Administrator)
    • 1. Web Interface Registration
    • 2. Project-Based Access Control
  • Installation
    • 1. Install Dependencies
    • 2. Install CipherSwarm Agent
  • Configuration
    • 1. Basic Setup
    • 2. Authentication Configuration
    • 3. Advanced Configuration
    • 4. Project Context
  • Running the Agent
    • 1. Systemd Service (Recommended)
    • 2. Docker Container
    • 3. Docker Compose
  • Agent Monitoring
    • Real-Time Status Updates
    • Agent List View
    • Hash Rate Monitoring
    • Error Badges and Notifications
    • Agent Detail Tabs
    • Performance Charts (8-Hour Trends)
  • Agent Management via Web Interface
    • 1. Agent Status Monitoring
    • 2. Configuration Management
    • 3. Performance Monitoring
  • Monitoring and Diagnostics
    • 1. Log Files
    • 2. Agent Status Commands
    • 3. Performance Metrics
  • Troubleshooting
    • 1. Authentication Issues
    • 2. Project Access Issues
    • 3. Performance Issues
    • 4. Common Problems
  • Maintenance
    • 1. Updates
    • 2. Token Rotation
    • 3. Backup and Recovery
    • 4. Cleanup
  • Security Best Practices
    • 1. Token Security
    • 2. Network Security
    • 3. System Security
    • 4. Container Security
  • Performance Optimization
    • 1. Hardware Optimization
    • 2. Configuration Tuning
    • 3. Monitoring and Tuning

Prerequisites#

1. System Requirements

   • hashcat 6.2.6 or higher
   • CUDA/OpenCL drivers (for GPU support)
   • 4GB RAM minimum
   • 10GB disk space

2. 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)

3. 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#

1. Login as Administrator

   • Access the CipherSwarm web interface
   • Login with administrator credentials

2. Navigate to Agent Management

   • Go to "Agents" section
   • Click "Register New Agent"

3. Configure Agent Details

   ⧉

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

4. 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#

1. 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

2. 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.)

3. 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

4. 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

5. 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

6. 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:

1. Administrator: Generate new token via web interface
2. Agent: Update configuration with new token
3. Restart: Restart agent service
4. 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