# How to Execute Chaos Experiments Remotely via SSH Channel in ChaosBlade

> Execute chaos experiments remotely via SSH channel with ChaosBlade. The --channel=ssh flag securely runs commands on target hosts without agents. Learn how now.

- Repository: [ChaosBlade/chaosblade](https://github.com/chaosblade-io/chaosblade)
- Tags: how-to-guide
- Published: 2026-02-27

---

**ChaosBlade enables you to execute chaos experiments remotely via SSH channel by passing the `--channel=ssh` flag, which delegates execution to the SSH executor that establishes a secure connection, deploys the binary, and runs commands on the target host without requiring a resident agent.**

ChaosBlade is an open-source chaos engineering platform that supports multiple execution modes for fault injection. When targeting infrastructure where you cannot install a permanent agent, you can execute chaos experiments remotely via SSH channel. This approach leverages the `--channel=ssh` flag to route commands through the SSH executor, enabling secure, on-demand fault injection against any reachable Linux host.

## How the SSH Channel Works

The SSH channel implementation follows a delegation pattern across the ChaosBlade executor stack. When you specify `--channel=ssh`, the core CLI builds an experiment model containing the channel flag, and the appropriate executor instantiates an `SSHExecutor` to handle remote communication.

### CLI to Experiment Model

In [`cli/cmd/create.go`](https://github.com/chaosblade-io/chaosblade/blob/main/cli/cmd/create.go), the `blade create` command parses user flags and constructs an `ExpModel`. When `--channel=ssh` is present, the model's `ActionFlags` map contains `channel: "ssh"`:

```go
// From cli/cmd/create.go
model.ActionFlags["channel"] = "ssh"
model.ActionFlags["target"] = "192.168.10.5"

```

### Executor Selection and Delegation

Each domain-specific executor checks the `channel` flag and delegates to the SSH executor when appropriate. In [`exec/os/executor.go`](https://github.com/chaosblade-io/chaosblade/blob/main/exec/os/executor.go), the OS executor detects the SSH channel and instantiates `exec.SSHExecutor`:

```go
// From exec/os/executor.go lines 42-48
if model.ActionFlags["channel"] == "ssh" {
    sshExecutor := &exec.SSHExecutor{}
    return sshExecutor.Exec(uid, ctx, model)
}

```

This pattern repeats across the middleware executor ([`exec/middleware/executor.go`](https://github.com/chaosblade-io/chaosblade/blob/main/exec/middleware/executor.go) lines 42-48), cloud executor ([`exec/cloud/executor.go`](https://github.com/chaosblade-io/chaosblade/blob/main/exec/cloud/executor.go) lines 42-48), and Kubernetes compose executor ([`exec/kubernetes/executor_compose.go`](https://github.com/chaosblade-io/chaosblade/blob/main/exec/kubernetes/executor_compose.go) lines 45-50), providing consistent SSH support across all target types.

### Remote Execution via SSHExecutor

The `SSHExecutor` implementation resides in the external module `chaosblade-exec-os` (version v1.8.0) within [`exec/ssh.go`](https://github.com/chaosblade-io/chaosblade/blob/main/exec/ssh.go). This executor:

- Establishes an SSH connection to the target host using configured credentials
- Copies the ChaosBlade binary to the remote host (or uses a pre-installed binary)
- Constructs the chaos command using the same arguments passed locally
- Executes the command remotely via `ssh <user>@<host> <command>`
- Captures the JSON-encoded `spec.Response` from the remote process and returns it to the local client

## Executing Remote Chaos Experiments via SSH

To execute chaos experiments remotely via SSH channel, append the `--channel=ssh` flag to any standard `blade create` command and specify the target host using `--target`.

### Running a CPU Burn Experiment on a Remote Host

The following command initiates a CPU burn experiment on a remote Linux host at `192.168.10.5`:

```bash
blade create cpu burn \
    --target=192.168.10.5 \
    --channel=ssh \
    --cpu-percent=80 \
    --timeout=60

```

The CLI constructs an `ExpModel` where `ActionFlags["channel"]="ssh"` and `Target="192.168.10.5"`. The OS executor detects the SSH flag, creates an `SSHExecutor`, and runs the remote command `chaos_os cpu burn --target=192.168.10.5 --cpu-percent=80 --timeout=60`.

### Destroying Remote Experiments

To stop a remote experiment, use the `blade destroy` command with the same channel and target flags, plus the experiment UID returned by the create command:

```bash
blade destroy cpu burn \
    --target=192.168.10.5 \
    --channel=ssh \
    --uid=1234567890abcdef

```

The destroy operation follows the same SSH delegation path, sending the destroy command to the remote host to clean up the injected fault.

### Programmatic Execution with the Go SDK

You can also execute chaos experiments remotely via SSH channel programmatically using the ChaosBlade Go SDK. Instantiate an `ExpModel` with the `channel` flag set to `ssh`:

```go
import (
    "context"
    "github.com/chaosblade-io/chaosblade-spec-go/spec"
    "github.com/chaosblade-io/chaosblade-spec-go/util"
)

func runRemoteCpuBurn() (*spec.Response, error) {
    model := &spec.ExpModel{
        Target:     "192.168.10.5",
        ActionName: "burn",
        ActionFlags: map[string]string{
            "cpu-percent": "80",
            "channel":     "ssh",  // Enable SSH channel
        },
    }
    uid := util.GenerateUID()
    ctx := context.Background()
    
    // Use the OS executor which will delegate to SSHExecutor
    executor := exec.NewExecutor()
    return executor.Exec(uid, ctx, model), nil
}

```

The SDK mirrors the CLI behavior: when `channel` is set to `ssh`, the executor delegates to `SSHExecutor` to handle the remote connection.

## Key Source Files and Implementation Details

The SSH channel implementation spans multiple modules across the ChaosBlade repository:

| Module | File | Purpose |
|--------|------|---------|
| **Core CLI** | [`cli/cmd/create.go`](https://github.com/chaosblade-io/chaosblade/blob/main/cli/cmd/create.go) | Parses the `--channel=ssh` flag and populates the `ExpModel.ActionFlags` map. |
| **OS Executor** | [`exec/os/executor.go`](https://github.com/chaosblade-io/chaosblade/blob/main/exec/os/executor.go) (lines 42-48) | OS executor that checks for `channel=ssh` and instantiates `SSHExecutor`. |
| **Middleware Executor** | [`exec/middleware/executor.go`](https://github.com/chaosblade-io/chaosblade/blob/main/exec/middleware/executor.go) (lines 42-48) | Middleware executor with identical SSH delegation logic. |
| **Kubernetes Compose Executor** | [`exec/kubernetes/executor_compose.go`](https://github.com/chaosblade-io/chaosblade/blob/main/exec/kubernetes/executor_compose.go) (lines 45-50) | Composite executor supporting SSH for pod-level experiments. |
| **Cloud Executor** | [`exec/cloud/executor.go`](https://github.com/chaosblade-io/chaosblade/blob/main/exec/cloud/executor.go) (lines 42-48) | Cloud executor supporting SSH for cloud instance targets. |
| **SSH Executor (external)** | [`chaosblade-exec-os/exec/ssh.go`](https://github.com/chaosblade-io/chaosblade/blob/main/chaosblade-exec-os/exec/ssh.go) (v1.8.0) | Core `SSHExecutor` implementing connection establishment, binary transfer, and remote command execution. |
| **Spec Utilities** | [`spec/response.go`](https://github.com/chaosblade-io/chaosblade/blob/main/spec/response.go) | JSON response handling shared between local and remote runs. |

These files illustrate how the **SSH channel flag** propagates from the CLI through the executor stack to the remote execution layer, enabling seamless chaos testing on any reachable host.

## Summary

- **ChaosBlade supports remote execution** via the `--channel=ssh` flag, enabling chaos experiments on any SSH-accessible host without requiring a resident agent.
- **The execution flow** moves from CLI parsing in [`cli/cmd/create.go`](https://github.com/chaosblade-io/chaosblade/blob/main/cli/cmd/create.go) through domain-specific executors ([`exec/os/executor.go`](https://github.com/chaosblade-io/chaosblade/blob/main/exec/os/executor.go), [`exec/middleware/executor.go`](https://github.com/chaosblade-io/chaosblade/blob/main/exec/middleware/executor.go), etc.) that delegate to `SSHExecutor` when the SSH channel is specified.
- **Remote implementation** is handled by the `SSHExecutor` in the `chaosblade-exec-os` module, which manages SSH connections, binary deployment, and JSON response handling.
- **Both CLI and Go SDK** support SSH channel execution using identical experiment models and flag configurations.

## Frequently Asked Questions

### Do I need to install ChaosBlade on the remote host before running experiments?

No. The `SSHExecutor` automatically copies the ChaosBlade binary to the remote host during the first connection if it is not already present. You can also pre-install the binary to skip the deployment step and reduce experiment startup time.

### How does authentication work for the SSH channel?

The SSH channel uses standard SSH authentication mechanisms. You can configure key-based authentication by ensuring your local SSH agent has the appropriate keys, or use password authentication if configured in your SSH client. The `SSHExecutor` in [`chaosblade-exec-os/exec/ssh.go`](https://github.com/chaosblade-io/chaosblade/blob/main/chaosblade-exec-os/exec/ssh.go) leverages the standard Go SSH client libraries to establish the connection.

### Can I use the SSH channel with Kubernetes or cloud experiments?

Yes. The SSH channel works across all executor types. The Kubernetes compose executor ([`exec/kubernetes/executor_compose.go`](https://github.com/chaosblade-io/chaosblade/blob/main/exec/kubernetes/executor_compose.go)) and cloud executor ([`exec/cloud/executor.go`](https://github.com/chaosblade-io/chaosblade/blob/main/exec/cloud/executor.go)) both check for the `channel=ssh` flag and delegate to `SSHExecutor` when specified. This allows you to run node-level chaos experiments on Kubernetes workers or cloud instances via SSH even when direct API access is unavailable.

### What is the performance impact of using SSH compared to local execution?

SSH channel execution introduces network latency for the initial connection and binary deployment (if not cached), plus the overhead of SSH encryption. However, the actual chaos experiment runs at native speed on the remote host. For long-running experiments (network delay, CPU burn, memory pressure), the initial SSH setup overhead is negligible. For very short experiments, consider pre-installing the binary to eliminate deployment time.