flashduty-runner

Flashduty Runner

English | 中文

Flashduty Runner is a lightweight, secure agent that runs in your environment to execute commands and access resources on behalf of Flashduty AI SRE platform.

How It Works

┌──────────────────┐       WebSocket (TLS)       ┌────────────────────┐
│  Flashduty AI    │ ◄─────────────────────────► │  Flashduty Runner  │
│  SRE Platform    │                             │  (Your Server)     │
└──────────────────┘                             └────────────────────┘
                                                          │
                                                          ▼
                                                 ┌────────────────────┐
                                                 │ • Execute Commands │
                                                 │ • Read/Write Files │
                                                 │ • MCP Tool Calls   │
                                                 └────────────────────┘

The runner establishes a persistent WebSocket connection to Flashduty cloud, receives task requests, executes them locally, and returns results.

Security

All code is open source - you can audit every line of code to verify exactly what the runner does.

Multi-layer Security Design

Permission Configuration

The runner uses glob pattern matching for command permissions. You have full control over what commands can be executed.

Option 1: Strict Mode (Recommended for shared environments)

Only allow specific commands explicitly:

permission:
  bash:
    "*": "deny"                  # Deny all by default
    "kubectl get *": "allow"
    "kubectl describe *": "allow"
    "kubectl logs *": "allow"
    "cat *": "allow"
    "ls *": "allow"

Option 2: Trust Mode (For dedicated/isolated environments)

If the runner is deployed in an isolated environment dedicated to AI operations, you can choose to trust the AI model's judgment:

permission:
  bash:
    "*": "allow"                 # Trust AI model
    "rm -rf /": "deny"           # Block catastrophic commands if desired

This mode is suitable when:

• The runner runs in an isolated VM/container with limited blast radius
• You trust the AI model's capabilities and want maximum flexibility
• Quick incident response is more important than restrictive permissions

Option 3: Read-Only Mode (For monitoring only)

permission:
  bash:
    "*": "deny"
    "cat *": "allow"
    "head *": "allow"
    "tail *": "allow"
    "ls *": "allow"
    "grep *": "allow"
    "ps *": "allow"
    "df *": "allow"
    "free *": "allow"

Quick Start

Binary Installation

# Linux (amd64)
curl -LO https://github.com/flashcatcloud/flashduty-runner/releases/latest/download/flashduty-runner_Linux_x86_64.tar.gz
tar -xzf flashduty-runner_Linux_x86_64.tar.gz
sudo mv flashduty-runner /usr/local/bin/

# Linux (arm64)
curl -LO https://github.com/flashcatcloud/flashduty-runner/releases/latest/download/flashduty-runner_Linux_arm64.tar.gz
tar -xzf flashduty-runner_Linux_arm64.tar.gz
sudo mv flashduty-runner /usr/local/bin/

# macOS (Apple Silicon)
curl -LO https://github.com/flashcatcloud/flashduty-runner/releases/latest/download/flashduty-runner_Darwin_arm64.tar.gz
tar -xzf flashduty-runner_Darwin_arm64.tar.gz
sudo mv flashduty-runner /usr/local/bin/

# macOS (Intel)
curl -LO https://github.com/flashcatcloud/flashduty-runner/releases/latest/download/flashduty-runner_Darwin_x86_64.tar.gz
tar -xzf flashduty-runner_Darwin_x86_64.tar.gz
sudo mv flashduty-runner /usr/local/bin/

Docker Installation

docker run -d \
  --name flashduty-runner \
  -e FLASHDUTY_RUNNER_API_KEY=your_api_key \
  -e FLASHDUTY_RUNNER_NAME=my-runner \
  -v /var/flashduty/workspace:/workspace \
  ghcr.io/flashcatcloud/flashduty-runner:latest

Configuration

Create ~/.flashduty-runner/config.yaml:

# API Key from Flashduty Console (required)
api_key: "fk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Runner display name (optional, defaults to hostname)
name: "prod-k8s-runner"

# Labels for task routing (optional)
labels:
  - k8s
  - production

# Workspace root directory (optional)
workspace_root: "/var/flashduty/workspace"

# Command permissions (see Security section for options)
permission:
  bash:
    "*": "deny"
    "kubectl get *": "allow"
    "kubectl describe *": "allow"
    "kubectl logs *": "allow"

Running

# Start the runner
flashduty-runner run

# Start with custom config
flashduty-runner run --config /path/to/config.yaml

# Check version
flashduty-runner version

Systemd Service (Linux)

Create /etc/systemd/system/flashduty-runner.service:

[Unit]
Description=Flashduty Runner
After=network.target

[Service]
Type=simple
User=flashduty
ExecStart=/usr/local/bin/flashduty-runner run
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now flashduty-runner

Configuration Reference

Environment Variables

All options can be set via environment variables with FLASHDUTY_RUNNER_ prefix:

FLASHDUTY_RUNNER_API_KEY=fk_xxx
FLASHDUTY_RUNNER_NAME=my-runner
FLASHDUTY_RUNNER_WORKSPACE_ROOT=/workspace

Built-in Labels

The runner automatically adds these labels for routing:

• os:linux / os:darwin / os:windows
• arch:amd64 / arch:arm64
• hostname:<machine-hostname>

Troubleshooting

Connection Issues

# Test connectivity
curl -v https://api.flashcat.cloud/health

# Check runner logs
journalctl -u flashduty-runner -f

Permission Issues

Permission Pattern Rules:

• Patterns are matched in order, last match wins
• * matches any characters
• Empty config defaults to deny all

Debug Mode

Enable debug logging to see detailed permission decisions:

log:
  level: "debug"

Contributing

We welcome contributions! Please see CONTRIBUTING.md.

License

Apache License 2.0 - see LICENSE.

Made with ❤️ by Flashcat