---
title: Core Architecture
description: The plugin registration, loading, and execution infrastructure.
icon: Binary
---
import { Steps, Step } from 'fumadocs-ui/components/steps';
The core architecture of the plugin system is designed to seamlessly bridge high-performance internal Rust components with flexible external scripts. It manages the lifecycle, discovery, and execution safety of all logic units.
## The Dual Registry Model
Vane maintains two distinct registries to handle the different lifecycles of plugins:
| Registry | Content | Lifecycle |
| :----------- | :------------------------------------------------------------ | :----------------------------------------- |
| **Internal** | Compiled-in Rust structs (e.g., `ProtocolDetect`, `TcpProxy`) | Static (Initialized at startup, read-only) |
| **External** | User-defined scripts/services defined in `plugins.json` | Dynamic (Hot-swappable via API/File) |
### Lookup Priority
When the Flow Executor requests a plugin by name, Vane checks the **Internal Registry** first. This prevents external plugins from shadowing critical system components.
## Loading Pipeline
<Mermaid
chart="
graph LR
Boot[Bootstrap] --> Init[loader::initialize];
Init --> Read[Read plugins.json];
Read --> Parse[Parse Config];
Parse --> Validate{Check Connectivity};
Validate -- OK --> Register[Update Registry];
Validate -- Fail --> Skip[Log Warning];
Register --> Monitor[Start Health Check];
"
/>
The loader performs a "connectivity check" before registering any external plugin.
- **HTTP**: Sends an `OPTIONS` request to the endpoint.
- **Unix**: Verifies the socket file exists.
- **Command**: Verifies the executable exists and is secure.
## Security: The Trusted Bin Root
For `command` driver plugins, Vane implements a strict security sandbox to prevent the execution of arbitrary system binaries.
**Rule**: All executable binaries MUST reside within the `bin/` subdirectory of the configuration folder.
```rust title="src/plugins/core/external.rs"
pub async fn validate_command_path(program: &str) -> Result<PathBuf> {
// ...
if !absolute_path.starts_with(&bin_root) {
return Err(anyhow!("Security Violation - Program is outside trusted bin directory."));
}
// ...
}
```
This prevents a malicious configuration from invoking sensitive system utilities like `/bin/sh` or `/usr/bin/nc`.
## Background Health Monitoring
To ensure stability, a background task runs periodically (default every 15 minutes) to re-validate external plugins.
- If a plugin becomes unreachable, its status in `EXTERNAL_PLUGIN_STATUS` is updated to `Error`.
- This status is exposed via the Management API, allowing operators to detect broken integrations proactively.
<Callout type="info" title="External Limitations">
Currently, external plugins can only function as **Middleware**. They cannot be **Terminators**
(i.e., they cannot perform the final proxying or connection upgrade actions). This restriction
ensures that the connection termination logic remains within the verified, memory-safe Rust core.
</Callout>