# How CyberStrikeAI Implements Hot-Reloading for Configurations Without Process Restarts

> Discover how CyberStrikeAI enables seamless configuration hot-reloading without process restarts. Learn about its REST API persistence and selective subsystem restarts for uninterrupted operation.

- Repository: [公明/CyberStrikeAI](https://github.com/Ed1s0nZ/CyberStrikeAI)
- Tags: internals
- Published: 2026-03-09

---

**CyberStrikeAI supports hot-reloading by persisting configuration changes to [`config.yaml`](https://github.com/Ed1s0nZ/CyberStrikeAI/blob/main/config.yaml) through a REST API, then selectively restarting only the affected subsystems—such as knowledge bases, external MCP servers, and robot connections—while the main process continues running.**

CyberStrikeAI (Ed1s0nZ/CyberStrikeAI) is an open-source AI security platform designed for dynamic operational environments where configuration updates cannot interrupt active services. The hot-reloading implementation allows administrators to modify [`config.yaml`](https://github.com/Ed1s0nZ/CyberStrikeAI/blob/main/config.yaml) settings via HTTP endpoints and apply changes instantly, ensuring continuous availability while updating complex subsystems like knowledge embeddings and external MCP integrations.

## The Three-Layer Hot-Reload Architecture

The hot-reloading system in [`internal/handler/config.go`](https://github.com/Ed1s0nZ/CyberStrikeAI/blob/main/internal/handler/config.go) operates through three coordinated layers that separate configuration persistence from live subsystem management.

### Configuration API Layer (ConfigHandler)

The **ConfigHandler** serves as the entry point for all configuration changes. The `UpdateConfig` function (lines 89-115 in [`internal/handler/config.go`](https://github.com/Ed1s0nZ/CyberStrikeAI/blob/main/internal/handler/config.go)) receives JSON payloads via HTTP POST, validates the structure, updates the in-memory `config.Config` struct, and calls `saveConfig()` to persist changes to [`config.yaml`](https://github.com/Ed1s0nZ/CyberStrikeAI/blob/main/config.yaml) on disk.

This layer ensures atomic write operations and maintains thread safety through write locks that protect the shared configuration state during updates.

### Live-Apply Logic Layer

The `ApplyConfig` function (lines 603-665 in [`internal/handler/config.go`](https://github.com/Ed1s0nZ/CyberStrikeAI/blob/main/internal/handler/config.go)) executes the actual hot-reload by comparing the new configuration against the current state and selectively restarting only affected components:

- **Knowledge Base Subsystem**: When `knowledge.enabled` toggles or the embedding model changes, the handler invokes the `knowledgeToolRegistrar` to recreate the knowledge subsystem and updates the `lastEmbeddingConfig` cache.
- **External MCP Servers**: Changes to `external_mcp.servers` propagate to `ExternalMCPManager` via `LoadConfigs`. Newly-enabled MCPs start asynchronously through `StartClient`, while the tool registry clears existing entries (`mcpServer.ClearTools()`) and reregisters internal security tools, external tools, vulnerability tools, Skills tools, and knowledge tools.
- **Agent and Robot Connections**: The handler refreshes the OpenAI client, updates iteration limits, and triggers `robotRestarter` to reconnect DingTalk and Lark long-polling connections with new credentials.

All operations occur under write locks, ensuring the server continues serving requests while subsystems restart.

### Background Refresh Layer

The **ExternalMCPManager** in [`internal/mcp/external_manager.go`](https://github.com/Ed1s0nZ/CyberStrikeAI/blob/main/internal/mcp/external_manager.go) maintains a background goroutine (`startToolCountRefresh`) that periodically updates cached tool-count maps without blocking requests. When external MCPs start or reconnect, the manager instantly refreshes its tool cache (`refreshToolCache`) and triggers asynchronous updates (`triggerToolCountRefresh`), allowing the UI to display newly-available tools immediately upon MCP availability.

## Key Source Files and Implementation Details

Understanding the hot-reload mechanism requires familiarity with these specific files:

- **[`internal/config/config.go`](https://github.com/Ed1s0nZ/CyberStrikeAI/blob/main/internal/config/config.go)**: Defines the central `Config` struct and performs initial parsing of [`config.yaml`](https://github.com/Ed1s0nZ/CyberStrikeAI/blob/main/config.yaml). All configurable sections—including knowledge base settings, external MCP servers, and robot credentials—are declared here.
- **[`internal/handler/config.go`](https://github.com/Ed1s0nZ/CyberStrikeAI/blob/main/internal/handler/config.go)**: Implements the `ConfigHandler` with `UpdateConfig` (lines 89-115) for persistence and `ApplyConfig` (lines 603-665) for live subsystem management. This file contains the core hot-reload orchestration logic.
- **[`internal/mcp/external_manager.go`](https://github.com/Ed1s0nZ/CyberStrikeAI/blob/main/internal/mcp/external_manager.go)**: Manages external MCP server lifecycles and background tool-cache refreshes. The `LoadConfigs`, `StartClient`, and `refreshToolCache` methods enable dynamic MCP registration without restarts.
- **[`internal/mcp/server.go`](https://github.com/Ed1s0nZ/CyberStrikeAI/blob/main/internal/mcp/server.go)**: Houses the tool registry that `ApplyConfig` clears and repopulates during hot-reloads. The `ClearTools()` method and registration functions for internal security tools are defined here.
- **[`internal/knowledge/manager.go`](https://github.com/Ed1s0nZ/CyberStrikeAI/blob/main/internal/knowledge/manager.go)**: Provides the `knowledgeToolRegistrar` interface that allows the knowledge base to be reinitialized on-the-fly when configuration changes affect embedding models or enablement status.

## Practical Example: Updating Configuration via API

Administrators trigger hot-reloads through two sequential API calls. First, update the configuration payload:

```bash
curl -X POST http://localhost:8080/api/config \
     -H "Content-Type: application/json" \
     -d '{"knowledge":{"enabled":false}}'

```

This invokes `UpdateConfig` in [`internal/handler/config.go`](https://github.com/Ed1s0nZ/CyberStrikeAI/blob/main/internal/handler/config.go), which writes the changes to [`config.yaml`](https://github.com/Ed1s0nZ/CyberStrikeAI/blob/main/config.yaml).

Next, apply the configuration to activate the hot-reload:

```bash
curl -X POST http://localhost:8080/api/config/apply

```

This triggers `ApplyConfig`, which detects the knowledge base disablement, calls the `knowledgeToolRegistrar` to tear down the subsystem, and updates the embedding configuration cache—all without restarting the main process.

## Summary

CyberStrikeAI implements hot-reloading through a coordinated three-layer architecture that separates configuration persistence from live subsystem management:

- **ConfigHandler** provides atomic updates to [`config.yaml`](https://github.com/Ed1s0nZ/CyberStrikeAI/blob/main/config.yaml) via REST API endpoints, protecting shared state with write locks.
- **ApplyConfig** selectively restarts only affected components—including knowledge bases, external MCP servers, and robot connections—while the main server continues operating.
- **ExternalMCPManager** maintains background goroutines for non-blocking tool-cache refreshes, ensuring UI consistency during dynamic MCP registration.

## Frequently Asked Questions

### How does CyberStrikeAI ensure thread safety during hot-reloads?

CyberStrikeAI protects the configuration state using write locks that guard the shared `config.Config` struct during updates. When `UpdateConfig` persists changes to disk or `ApplyConfig` reinitializes subsystems, these locks ensure the server continues serving requests without race conditions while subsystems restart.

### Can I update external MCP server configurations without restarting CyberStrikeAI?

Yes. Changes to the `external_mcp.servers` section propagate to `ExternalMCPManager` via `LoadConfigs`, which automatically starts newly-enabled MCPs asynchronously through `StartClient`. The system clears the existing tool registry (`mcpServer.ClearTools()`), reregisters internal and external tools, and refreshes tool caches in the background without requiring a process restart.

### What happens to active connections when robot credentials change in config.yaml?

When robot configuration changes—such as DingTalk or Lark credentials—`ApplyConfig` triggers the `robotRestarter` to reconnect long-polling connections using the new credentials. This occurs seamlessly while other server functions continue operating, ensuring bot integrations remain functional without service interruption.

### Is the knowledge base subsystem recreated for every configuration change?

No. The knowledge base subsystem is only recreated when specific configuration fields change, such as `knowledge.enabled` toggling or modifications to the embedding model configuration. `ApplyConfig` compares the new configuration against `lastEmbeddingConfig` and only invokes `knowledgeToolRegistrar` when necessary, minimizing overhead during unrelated configuration updates.