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)

# Storage Configuration (network-share feature)
KH_STORAGE_TIER=full_cache        # full_cache (default) | on_demand | network_direct
KH_NETWORK_SHARE_MOUNT_PATH=      # Read-only mount path for the network_direct tier

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

1. 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
  -storage-tier string             full_cache (default) | on_demand | network_direct (seeds the server at registration)
  -network-share-mount-path string Read-only mount path for the network_direct tier (e.g. /mnt/kh-agent-share)
  -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: By default 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.

The exception is ephemeral mode (--ephemeral / KH_EPHEMERAL=true), where the order becomes:

1. Default values
2. System environment variables
3. Command line flags

and no .env file is read or written. Use it for containers and rented cloud instances.

Storage Tier (network-share feature)¶

An agent can obtain wordlists/rules in one of three tiers:

Set the tier with --storage-tier / KH_STORAGE_TIER, and the read-only share mount with --network-share-mount-path / KH_NETWORK_SHARE_MOUNT_PATH. You must mount the share yourself at that path before starting the agent — the agent never mounts anything, and it refuses to start if its own binary lives on a network mount.

These settings are a seed: they set the agent's initial tier/mount and are reported to the server when the agent registers. After that, the admin UI (Admin → System Settings → Storage, per agent) is authoritative and can override them; the server re-asserts its stored value on each reconnect. A tier of network_direct with no mount path, or an unknown tier, falls back to full_cache so a misconfigured agent still starts.

# On-prem network_direct agent (share already mounted read-only at the path)
./krakenhashes-agent \
  -host your-server:31337 \
  -claim YOUR_CLAIM_CODE \
  -storage-tier network_direct \
  -network-share-mount-path /mnt/kh-agent-share

Latency & remote shares¶

Use network_direct only for a low-latency, LAN-adjacent share (your host on the same network as the server's share). Every job reads the whole wordlist off the mount before hashcat starts, so a remote/high-latency share (another building, state, or country) stalls startup. For those, run the agent on full_cache or on_demand instead — they download over the HTTP relay, which tolerates a slow link far better than a kernel mount.

When you do mount a share, prefer fail-fast options so a dropped share returns an error quickly instead of hanging the agent (the Storage panel's generated command does this for you):

• NFS: soft,timeo=150,retrans=2 (≈30 s to an I/O error) rather than the kernel hard default.
• SMB/CIFS: soft.

The agent backs this up: it runs a bounded, background check on the mount and reports itself not ready if the mount is slow or gone (the scheduler then reroutes work), without ever blocking its own heartbeat. A slow share costs time, not failed jobs — the server widens the benchmark/startup windows for network_direct agents and does not count a share-read benchmark timeout against the agent. If a share keeps timing out even so, move the agent to full_cache/on_demand.

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¶

• Set up agent scheduling
• Configure file synchronization
• Monitor agent performance