Skip to content

Agent Configuration

Overview

This guide covers all configuration options available for KrakenHashes agents.

Configuration File

The agent uses a .env configuration file that is automatically created on first run. The file is located in the agent's working directory and contains all necessary configuration.

Location

  • Default: ./.env (in the current working directory)
  • Custom: Specified via command-line flags on first run

Configuration Management

The .env file is automatically managed by the agent: - Created on first run with values from command-line flags - Updated with any missing configuration keys on subsequent runs - Preserves existing values when new options are added

Manual Editing

You can manually edit the .env file to adjust configuration:

# Stop the agent (choose based on your setup)

# For manual run: Ctrl+C in the terminal or kill the process
# For user service:
systemctl --user stop krakenhashes-agent
# For system service:
sudo systemctl stop krakenhashes-agent

# Edit the configuration
nano .env

# Restart the agent

# For manual run:
./krakenhashes-agent
# For user service:
systemctl --user start krakenhashes-agent
# For system service:
sudo systemctl start krakenhashes-agent

Note: If you haven't set up systemd yet, see the Systemd Service Setup guide for automatic startup and easier management.

Environment Variables (.env File)

The agent uses a .env file for configuration, which is automatically created during first run. The file is loaded at startup and values are NOT taken from system environment variables to avoid conflicts when running on the same host as the backend.

Complete .env File Example

This is the actual .env file generated by the agent on first run:

# KrakenHashes Agent Configuration
# Generated on: 2025-09-05T12:05:32+01:00

# Server Configuration
KH_HOST=your-server.example.com  # Backend server hostname
KH_PORT=31337                    # Backend server port
USE_TLS=true                     # Use TLS for secure communication (wss:// and https://)
LISTEN_INTERFACE=                # Network interface to bind to (leave empty for all)
HEARTBEAT_INTERVAL=5             # Heartbeat interval in seconds

# Agent Configuration
KH_CLAIM_CODE=YOUR-CLAIM-CODE-HERE  # Claim code for first-time registration (auto-commented after success)

# Directory Configuration
KH_CONFIG_DIR=./config  # Configuration directory for certificates and credentials
KH_DATA_DIR=./data      # Data directory for binaries, wordlists, rules, and hashlists

# WebSocket Timing Configuration
KH_WRITE_WAIT=10s   # Timeout for writing messages to WebSocket
KH_PONG_WAIT=60s    # Timeout for receiving pong from server
KH_PING_PERIOD=54s  # Interval for sending ping to server (must be less than pong wait)

# File Transfer Configuration
KH_MAX_CONCURRENT_DOWNLOADS=3  # Maximum number of concurrent file downloads
KH_DOWNLOAD_TIMEOUT=1h         # Timeout for large file downloads

# Hashcat Configuration
HASHCAT_EXTRA_PARAMS=  # Extra parameters to pass to hashcat (e.g., "-O -w 3" for optimized kernels and high workload)

# Logging Configuration
DEBUG=false            # Enable debug logging
LOG_LEVEL=INFO        # Log level (DEBUG, INFO, WARNING, ERROR)

Important: Hashcat Parameter Precedence

HASHCAT_EXTRA_PARAMS Behavior: - Parameters configured in the frontend/backend (per-agent settings) take precedence over the agent's .env file - The agent's .env HASHCAT_EXTRA_PARAMS is only used as a fallback when the backend doesn't send any parameters - Best Practice: Configure agent parameters via the frontend UI for centralized management - Only use .env parameters for local overrides that should NOT be managed by the backend

Parameter Priority (highest to lowest): 1. Backend/Frontend per-agent settings (stored in database) 2. Agent .env file HASHCAT_EXTRA_PARAMS (fallback only)

Manual .env File Creation

You can manually create a .env file for agent registration instead of using command-line flags:

  1. Create a .env file in the agent's working directory
  2. Copy the example above and fill in your values:
  3. Set KH_HOST to your backend server hostname
  4. Set KH_PORT to your backend server port (usually 31337)
  5. Set KH_CLAIM_CODE to your claim code (get from Admin UI)
  6. Adjust directory paths as needed
  7. Run the agent without any flags: ./krakenhashes-agent
  8. After successful registration, the claim code will be automatically commented out

Note: The agent reads from the .env file, not from system environment variables. This prevents conflicts when running the agent and backend on the same host.

Command Line Options

krakenhashes-agent [flags]

Flags:
  -host string           Backend server host (e.g., localhost:31337)
  -tls                   Use TLS for secure communication (default: true)
  -interface string      Network interface to listen on (optional)
  -heartbeat int         Heartbeat interval in seconds (default: 5)
  -claim string          Agent claim code (required only for first-time registration)
  -debug                 Enable debug logging (default: false)
  -hashcat-params string Extra parameters to pass to hashcat (e.g., '-O -w 3')
  -config-dir string     Configuration directory for certificates and credentials
  -data-dir string       Data directory for binaries, wordlists, rules, and hashlists
  -help                  Show help

Example Usage

# First-time registration from agent directory
cd ~/krakenhashes-agent
./krakenhashes-agent \
  -host your-server:31337 \
  -claim YOUR_CLAIM_CODE \
  -debug

# Subsequent runs (uses .env file created during first run)
cd ~/krakenhashes-agent
./krakenhashes-agent

# Override specific settings
./krakenhashes-agent -debug -hashcat-params "-O -w 4"

Configuration Precedence

Settings are applied in this order (later overrides earlier): 1. Default values 2. .env file values (created/updated on first run) 3. Command line flags

Important: The agent does NOT read from system environment variables to avoid conflicts when running on the same host as the backend. All configuration is handled through the .env file and command-line flags.

Device Configuration

Enabling/Disabling Devices

You can control which devices the agent uses:

devices:
  # Disable specific device IDs
  disabled_devices:
    - 0  # Disable first GPU

  # Or only enable specific devices
  enabled_devices:
    - 1
    - 2

Device-Specific Settings

devices:
  # Per-device temperature limits
  device_temps:
    0: 80  # Device 0 max temp
    1: 85  # Device 1 max temp

  # Per-device workload
  device_workloads:
    0: 2  # Lower workload for device 0
    1: 4  # Higher workload for device 1

Security Configuration

TLS/SSL Settings

tls:
  # Skip certificate verification (not recommended)
  insecure_skip_verify: false

  # Custom CA certificate
  ca_cert_file: /etc/krakenhashes/ca.crt

  # Client certificates (if required)
  client_cert_file: /etc/krakenhashes/client.crt
  client_key_file: /etc/krakenhashes/client.key

API Key Security

  • API keys are stored encrypted in the config file
  • Keys are never logged or displayed after registration
  • Regenerate keys if compromised

Performance Tuning

Memory Management

performance:
  # Hashcat memory settings
  hashcat_memory_limit: 4096  # MB per device

  # System memory reservation
  system_memory_reserve: 2048  # MB to leave free

  # File cache settings
  max_cache_size: 10240  # MB for wordlists/rules

GPU Optimization

performance:
  # GPU utilization target
  gpu_utilization_target: 90  # Percent

  # Kernel tuning
  kernel_accel: 0  # 0=auto, or specific value
  kernel_loops: 0  # 0=auto, or specific value

  # Power management
  gpu_power_tune: 0  # Percent adjustment (-50 to +50)

Monitoring Configuration

monitoring:
  # Metrics collection
  collect_metrics: true
  metrics_interval: 30  # seconds

  # Hardware monitoring
  monitor_temps: true
  monitor_fan_speed: true
  monitor_power: true
  monitor_memory: true

  # Alerts
  alerts:
    high_temp_threshold: 85
    low_hashrate_threshold: 1000000  # H/s
    error_rate_threshold: 0.05  # 5%

Scheduling Configuration

See Agent Scheduling for detailed scheduling configuration.

Troubleshooting Configuration Issues

Debug Mode

Enable debug logging to see configuration loading: 

cd ~/krakenhashes-agent
./krakenhashes-agent -debug

This will show: - Configuration file loading - Connection attempts - Certificate validation - File synchronization

Common Issues

  1. Permission Denied: Ensure agent user can read config file
  2. Invalid YAML: Use a YAML validator
  3. Missing Required Fields: Check server URL and data directory
  4. Environment Variable Conflicts: Check for conflicting env vars

Best Practices

  1. Use Configuration Management: Store configs in Git/Ansible
  2. Secure API Keys: Use appropriate file permissions (600)
  3. Monitor Logs: Set up log rotation and monitoring
  4. Test Changes: Validate config before restarting agent
  5. Document Custom Settings: Keep notes on non-default values

Next Steps