Setting Up CipherSwarmAgent and Hashcat#

This guide describes how to install and configure CipherSwarmAgent on Windows, Linux, and macOS, including requirements and steps for enabling GPU acceleration with Nvidia, AMD, Apple Silicon, and Intel GPUs, following current Hashcat guidance.

1. Prerequisites#

• API Token and URL: Obtain an API token and the server URL from your CipherSwarm administrator.
• Go 1.22+ and Git (for building from source, optional).
• Hashcat: Required for native installations (see platform-specific instructions below).
• GPU Drivers: Install the latest drivers for your GPU (see section 4).

2. Installation Methods#

a. Pre-built Binaries (Recommended)#

Download the latest release for your platform from the CipherSwarmAgent releases page.

Linux x86_64:

wget https://github.com/unclesp1d3r/CipherSwarmAgent/releases/latest/download/CipherSwarmAgent_Linux_x86_64.tar.gz
tar -xzf CipherSwarmAgent_Linux_x86_64.tar.gz
chmod +x cipherswarm-agent

macOS (Intel):

wget https://github.com/unclesp1d3r/CipherSwarmAgent/releases/latest/download/CipherSwarmAgent_Darwin_x86_64.tar.gz
tar -xzf CipherSwarmAgent_Darwin_x86_64.tar.gz
chmod +x cipherswarm-agent

macOS (Apple Silicon):

wget https://github.com/unclesp1d3r/CipherSwarmAgent/releases/latest/download/CipherSwarmAgent_Darwin_arm64.tar.gz
tar -xzf CipherSwarmAgent_Darwin_arm64.tar.gz
chmod +x cipherswarm-agent

Windows x86_64:

wget https://github.com/unclesp1d3r/CipherSwarmAgent/releases/latest/download/CipherSwarmAgent_Windows_x86_64.zip -OutFile CipherSwarmAgent_Windows_x86_64.zip
Expand-Archive -Path CipherSwarmAgent_Windows_x86_64.zip -DestinationPath .
cipherswarm-agent.exe

Reference

b. Docker (Easiest, All Dependencies Included)#

docker pull ghcr.io/unclesp1d3r/cipherswarmagent:latest
docker run -e API_TOKEN=your_api_token -e API_URL=https://your-server.com:3000 ghcr.io/unclesp1d3r/cipherswarmagent:latest

The Docker image includes Hashcat and all dependencies. For GPU access, see section 4.

c. From Source#

Requires Go 1.22+ and Git.

git clone https://github.com/unclesp1d3r/CipherSwarmAgent.git
cd CipherSwarmAgent
go build -o cipherswarm-agent

d. Linux Package Managers#

# Debian/Ubuntu
wget https://github.com/unclesp1d3r/CipherSwarmAgent/releases/latest/download/cipherswarm-agent_x.x.x_linux_amd64.deb
sudo dpkg -i cipherswarm-agent_x.x.x_linux_amd64.deb

# Red Hat/CentOS
wget https://github.com/unclesp1d3r/CipherSwarmAgent/releases/latest/download/cipherswarm-agent_x.x.x_linux_amd64.rpm
sudo rpm -i cipherswarm-agent_x.x.x_linux_amd64.rpm

Reference

3. Hashcat Installation#

If not using Docker, install Hashcat natively:

Linux:

# Ubuntu/Debian
sudo apt update && sudo apt install hashcat
# Red Hat/CentOS
sudo dnf install hashcat
# Arch Linux
sudo pacman -S hashcat

macOS:

brew install hashcat

Windows:
Download from hashcat.net and add the directory to your PATH.

The agent will use the system's native Hashcat binary by default, or you can force this with the ALWAYS_USE_NATIVE_HASHCAT environment variable or --always_use_native_hashcat flag. If you need to use a specific Hashcat binary or have multiple versions installed, you can specify the path using the --hashcat-path flag when running the agent.
Reference

4. GPU Requirements and Setup#

General Guidance#

• Install the latest GPU drivers for your hardware from the vendor's official site.
• Hashcat is responsible for GPU detection and utilization. The agent shells out to Hashcat, which manages device selection and backend (CUDA, OpenCL, Metal) automatically.
• Verify GPU support with hashcat --backend-info or hashcat -I.

Platform and Vendor-Specific Notes#

• Nvidia: Install the latest proprietary driver and CUDA toolkit (Linux), or the official driver (Windows).
• AMD: Install ROCm (Linux, where supported) or the official driver with OpenCL support (Windows/macOS).
• Intel: Install the latest OpenCL runtime (Linux/Windows/macOS).
• Apple Silicon: No driver installation required; Metal backend is used natively by Hashcat on M1/M2/M3 chips.

Docker GPU Access:

• For Nvidia GPUs, use the NVIDIA Container Toolkit and run containers with --gpus all.
• For AMD GPUs, OpenCL support in containers is experimental; consult ROCm and Docker documentation.
• For Apple Silicon, use native installation (Docker GPU passthrough is not supported).

Example Docker Compose for Nvidia:

services:
  cipherswarm-agent:
    image: ghcr.io/unclesp1d3r/cipherswarmagent:latest
    environment:
      - API_TOKEN=your_api_token
      - API_URL=https://your-server.com:3000
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

Reference

5. Configuration#

You can configure the agent using environment variables, command-line flags, or a YAML config file (cipherswarmagent.yaml). The two required settings are:

• API_TOKEN: Your agent token.
• API_URL: The CipherSwarm server URL.

Example:

export API_TOKEN=your_token
export API_URL=https://your-server.com:3000
./cipherswarm-agent

Optional GPU-related settings:

• GPU_TEMP_THRESHOLD (default: 80): Maximum GPU temperature in °C before pausing tasks.
• ALWAYS_USE_NATIVE_HASHCAT (default: false): Force use of system Hashcat binary.

Optional benchmark settings:

• FORCE_BENCHMARK_RUN (default: false): Force fresh benchmark runs instead of using cached results.
• DEFER_BENCHMARKS (CLI: --defer-benchmarks, default: false): Skip full GPU benchmarks at startup; use hashcat's quick --hash-info capability detection instead. Reduces agent startup time from several minutes to seconds. Placeholder benchmark results are submitted immediately so the server knows which hash types are supported; real benchmarks are then run in the background during idle periods. Recommended for agents with large GPU setups or where fast restarts are required.
• BENCHMARK_WHILE_IDLE (CLI: --benchmark-while-idle, default: true): When deferred benchmarks are enabled, run real background benchmarks one hash type at a time during idle periods, progressively replacing the placeholder results submitted at startup. Background benchmarks are automatically paused while a cracking task is running to avoid GPU contention.

Additional configuration flags:

• --hashcat-path: Path to custom Hashcat binary (overrides automatic detection)
• --always-trust-files: Skip checksum verification for downloaded files (not recommended)
• --enable-additional-hash-types (default: true): Enable support for additional hash types during benchmarking

These flags can also be set via environment variables (uppercase with underscores, e.g., HASHCAT_PATH) or in the YAML configuration file. For complete details on all available configuration options, see the configuration.md documentation.

Example YAML:

api_token: your_token
api_url: https://your-server.com:3000
gpu_temp_threshold: 80
always_use_native_hashcat: true
force_benchmark_run: false
defer_benchmarks: false # Set to true for fast startup (defers full benchmarks to idle time)
benchmark_while_idle: true # Run background benchmarks during idle when defer_benchmarks is enabled
hashcat_path: '' # Leave empty for auto-detection
enable_additional_hash_types: true

Reference

Network Resilience Settings (Optional)#

The agent includes automatic retry logic and circuit breaker protection for network failures. You can customize these settings if needed:

agent:
  # HTTP timeout settings
  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

  # Automatic retry settings
  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 settings
  circuit_breaker_failure_threshold: 5 # failures before circuit opens
  circuit_breaker_timeout: 60 # seconds - duration before retry attempt

Note: The server can provide recommended timeout and retry settings that override these local values. Most users can leave these at defaults. For detailed information about how these settings affect agent behavior, see Agent Network and Connection Issues.

6. Running the Agent#

Start the agent with:

./cipherswarm-agent

Or, with custom config:

./cipherswarm-agent --config /path/to/config.yaml

Or, with Docker:

docker run -e API_TOKEN=your_token -e API_URL=https://your-server.com:3000 ghcr.io/unclesp1d3r/cipherswarmagent:latest

Network Resilience Features: The agent automatically handles network interruptions through retry logic (up to 3 attempts with exponential backoff) and circuit breaker protection. If you see "circuit breaker open" messages in logs, this means the agent is protecting against repeated connection failures - it will automatically attempt recovery. No restart is needed.

Startup Benchmark Behavior:

By default, the agent runs full GPU benchmarks at startup before entering the main task loop. On systems with multiple or high-end GPUs, this can take several minutes. To reduce startup time to seconds, use the --defer-benchmarks flag:

./cipherswarm-agent --defer-benchmarks

With --defer-benchmarks enabled, the agent performs a quick capability detection pass using hashcat --hash-info --machine-readable at startup, submits placeholder results to the server, and immediately enters the main task loop. Real benchmarks are then run one hash type at a time in the background during idle periods (when no cracking task is active), progressively replacing the placeholders. This mode is particularly useful in lab environments with large GPU arrays or where agents must restart frequently.

To disable background benchmarking while still using deferred startup (e.g., you plan to trigger benchmarks manually), set benchmark_while_idle: false or use --benchmark-while-idle=false.

Benchmark Caching and Retry Behavior:

The agent persistently caches benchmark results to disk at <data_path>/benchmark_cache.json (where data_path is configurable). This allows benchmark results to survive agent restarts, eliminating the need to re-run time-consuming benchmarks on every startup.

The agent preserves partial benchmark results when interrupted during benchmarking (e.g., Ctrl+C, SIGTERM, service stop, context cancellation). When the agent is interrupted, it saves any collected results to the cache using atomic writes (write to a temporary file, then rename) for crash safety. The cache file is always left in a valid state, even if the agent is forcibly terminated.

Server-Driven Benchmark Control:

The server provides a benchmarks_needed boolean flag in the agent configuration API response that determines whether the agent should run benchmarks. This mechanism improves agent startup time by avoiding unnecessary benchmark runs when valid results already exist on the server.

When benchmarks_needed is false:
The server already has valid cached benchmark results for this agent, so the agent skips benchmark execution entirely. The agent logs "Server reports valid benchmarks on file, skipping benchmark run" and marks benchmarks as submitted without running Hashcat.

When benchmarks_needed is true:
The server requires fresh benchmark data from this agent. The agent performs a full benchmark run and submits the results to the server. This occurs during initial startup or when the server requests updated benchmarks (e.g., during a configuration reload).

Force Benchmark Override:
The --force-benchmark CLI flag overrides the server's benchmarks_needed signal. When this flag is set, the agent performs benchmark runs regardless of the server's preferences. This is useful after hardware changes or for troubleshooting.

Retry Behavior:

If benchmark submission to the server fails (e.g., due to temporary network issues or server problems), the agent implements a bounded retry mechanism that attempts submission up to 10 times before escalating the error to the server. The cache persists between retries, ensuring benchmarks don't need to be re-run just because of transient failures.

When you restart the agent after an interrupted benchmark run, you may see immediate benchmark submission attempts in the logs. This is the agent automatically retrying cached results from the previous interrupted session via TrySubmitCachedBenchmarks. Once the cached results are successfully submitted to the server, the agent marks them as submitted and continues normal operation without re-running the benchmarks.

Force Fresh Benchmarks:

To bypass the cache and force the agent to regenerate benchmark data (useful after hardware changes or for troubleshooting), use the --force-benchmark flag:

./cipherswarm-agent --force-benchmark

Reference

7. Verifying GPU and Hashcat#

• Check GPU detection: hashcat --backend-info
• Check Hashcat version: hashcat --version
• Monitor agent logs for device enumeration and task execution.

8. Troubleshooting#

• Hashcat not found: Ensure Hashcat is installed and in your PATH, or use Docker.
• GPU not detected: Verify driver installation and use hashcat --backend-info.
• Permission errors: Ensure the agent binary is executable and has access to required directories.
• Docker GPU issues: Ensure the container has access to the GPU (see section 4).
• Circuit Breaker Activation: If you see "circuit breaker open" messages during testing, verify the server URL is correct and the CipherSwarm server is running and accessible. The circuit breaker activates after 5 consecutive connection failures to protect the agent. It will automatically attempt recovery after 60 seconds. See Circuit Breaker Recovery for details.

For comprehensive troubleshooting guidance including network issues, task acceptance failures, and monitoring, see the CipherSwarm Troubleshooting Guide.

Reference

9. Current Hashcat Version#

CipherSwarmAgent uses the system's installed Hashcat binary by default. To check the version in use, run:

hashcat --version

The agent will use whatever version is installed or provided in the Docker image. Always use the latest stable Hashcat release for best compatibility and performance.

Reference

10. Additional Notes#

• The agent supports device selection and backend prioritization via configuration, but actual GPU/driver requirements are enforced by Hashcat.
• For advanced device configuration, consult the agent's YAML schema and Hashcat's documentation for backend and device selection options.
• For the latest GPU and driver requirements, always refer to Hashcat's official documentation.

For further details, consult the CipherSwarmAgent documentation and Hashcat documentation.