# How HTTP Server Mode Enables Remote Chaos Execution in ChaosBlade

> Explore how ChaosBlade's HTTP server mode enables remote chaos execution. Trigger experiments via RESTful API using the same pipeline as the CLI for seamless control.

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

---

**ChaosBlade's HTTP server mode launches a background daemon that exposes a RESTful endpoint at `/chaosblade`, allowing remote clients to trigger chaos experiments via standard HTTP requests using the same execution pipeline as the local CLI.**

The chaosblade-io/chaosblade project provides an HTTP server mode that transforms the command-line tool into a remotely accessible chaos engineering platform. By running `blade server start`, operators can expose the experiment execution engine through a RESTful interface, enabling automated orchestration tools and remote clients to inject failures without requiring direct shell access to target hosts.

## Architecture of the HTTP Server Mode

### The StartServerCommand Implementation

The server mode centers on the `StartServerCommand` struct defined in [`cli/cmd/server_start.go`](https://github.com/chaosblade-io/chaosblade/blob/main/cli/cmd/server_start.go). This command implements the `Command` interface and orchestrates the daemon lifecycle through several distinct phases, from CLI flag parsing to HTTP listener initialization.

### CLI Flag Parsing and Process Management

At lines 55-58 of [`cli/cmd/server_start.go`](https://github.com/chaosblade-io/chaosblade/blob/main/cli/cmd/server_start.go), the command parses three critical flags:

- `--ip`: The bind address (defaults to `127.0.0.1`)
- `--port`: The listening port (defaults to `9526`)
- `--nohup`: Internal flag indicating background daemon mode

Before launching, the code checks for existing server processes using `channel.NewLocalChannel().GetPidsByProcessName(startServerKey, ...)` at lines 60-68, preventing duplicate daemon instances that could cause port conflicts.

## How Remote Chaos Execution Works

### The /chaosblade Endpoint Registration

When the server initializes via `start0()` (lines 69-71), it spawns an HTTP listener in a goroutine. The core registration happens at lines 32-34:

```go
go func() {
    http.ListenAndServe(ssc.ip+":"+ssc.port, nil)
}()
Register("/chaosblade")

```

This binds the `/chaosblade` path to the default `http.ServeMux`, creating the entry point for remote experiment requests.

### Request Processing Pipeline

The handler implementation at lines 36-40 currently returns a placeholder response for security reasons:

```go
http.HandleFunc(requestPath, func(w http.ResponseWriter, r *http.Request) {
    // Server mode is disabled in open source for security
    spec.ReturnFail(spec.CommandIllegal, "Server mode is disabled")
})

```

In production deployments, this handler parses incoming JSON payloads, constructs `spec.ExpModel` objects, invokes the same execution pipeline used by the CLI (`command.Execute`), and returns JSON-encoded `spec.Response` objects. The `util.Hold()` function in [`util/hold.go`](https://github.com/chaosblade-io/chaosblade/blob/main/util/hold.go) maintains the main goroutine while the HTTP server runs in the background, preventing the process from exiting.

## Starting and Managing the Server Daemon

To launch the HTTP server as a background process:

```bash

# Start daemon on all interfaces, port 9526

blade server start --nohup --ip 0.0.0.0 --port 9526

```

Check server status:

```bash
blade server status

```

Stop the daemon:

```bash
blade server stop

```

The [`server_stop.go`](https://github.com/chaosblade-io/chaosblade/blob/main/server_stop.go) implementation locates the process using `GetPidsByProcessName` and sends termination signals, while [`server_status.go`](https://github.com/chaosblade-io/chaosblade/blob/main/server_status.go) reports whether the daemon is active and on which port it listens.

## Security Considerations for Remote Execution

The open-source implementation intentionally disables remote execution at `cli/cmd/server_start.go:L38-L40` to prevent unauthorized chaos injection. Production implementations should replace the placeholder handler with:

- **TLS encryption** for transport security
- **Authentication tokens** or API keys
- **RBAC policies** restricting experiment types
- **Audit logging** of all remote requests

When properly secured, the HTTP server mode enables safe remote chaos engineering orchestration through standardized RESTful interfaces.

## Summary

- ChaosBlade's HTTP server mode transforms the CLI into a remote-accessible daemon via `blade server start`
- The implementation in [`cli/cmd/server_start.go`](https://github.com/chaosblade-io/chaosblade/blob/main/cli/cmd/server_start.go) spawns an HTTP listener on a configurable IP and port (default 9526)
- The `/chaosblade` endpoint receives remote requests and processes them through the same execution pipeline as local CLI commands
- The open-source version returns "Server mode is disabled" for security; production deployments implement proper authentication and TLS
- Supporting commands in [`server_stop.go`](https://github.com/chaosblade-io/chaosblade/blob/main/server_stop.go) and [`server_status.go`](https://github.com/chaosblade-io/chaosblade/blob/main/server_status.go) provide lifecycle management for the background daemon

## Frequently Asked Questions

### How do I start the ChaosBlade HTTP server?

Execute `blade server start --nohup --port 9526` to launch the daemon in background mode. The `--nohup` flag is required for daemonization, while `--ip` and `--port` configure the bind address (defaulting to 127.0.0.1:9526). The server process runs within the same `blade` binary rather than spawning a separate executable.

### What endpoint does the server expose for remote chaos execution?

The server registers the `/chaosblade` path on the default `http.ServeMux` via the `Register("/chaosblade")` function in [`cli/cmd/server_start.go`](https://github.com/chaosblade-io/chaosblade/blob/main/cli/cmd/server_start.go). All remote experiment requests must target this endpoint using HTTP methods. The handler is bound through `http.HandleFunc` at lines 36-40 of the same file.

### Why does the server return "Server mode is disabled" when I try to execute experiments?

The open-source master branch intentionally disables remote execution at lines 38-40 of [`cli/cmd/server_start.go`](https://github.com/chaosblade-io/chaosblade/blob/main/cli/cmd/server_start.go) to prevent unauthorized access to dangerous chaos engineering capabilities. The handler explicitly calls `spec.ReturnFail(spec.CommandIllegal, "Server mode is disabled")`. Production deployments must replace the placeholder handler with proper authentication, authorization, and TLS encryption before enabling remote execution.

### How can I stop a running ChaosBlade server?

Use the `blade server stop` command, which executes the logic in [`cli/cmd/server_stop.go`](https://github.com/chaosblade-io/chaosblade/blob/main/cli/cmd/server_stop.go) to locate the daemon process using `GetPidsByProcessName` and send termination signals. Alternatively, you can check the server status first with `blade server status` to verify it is running and on which port. The status command is implemented in [`cli/cmd/server_status.go`](https://github.com/chaosblade-io/chaosblade/blob/main/cli/cmd/server_status.go).