How CyberStrikeAI Implements Hot-Reloading for Configurations Without Process Restarts

CyberStrikeAI supports hot-reloading by persisting configuration changes to 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 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 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) 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 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) 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 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: Defines the central Config struct and performs initial parsing of config.yaml. All configurable sections—including knowledge base settings, external MCP servers, and robot credentials—are declared here.
• 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: 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: 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: 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:

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, which writes the changes to config.yaml.

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

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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}