Extensions & Plugins

openarko adopts a standardized physical storage architecture and dynamic extension lifecycle governance, enabling tools, capabilities, and channels to plug in safely.

Physical Storage Architecture

The host device organizes extension assets into clearly separated physical tiers for immutable distribution archives and ready-to-run environments:

1. Download Cache Directory (~/.openarko/cache/)

• Immutable Package Fact Source: Exclusively stores original downloaded package archives (such as .tar.gz or .zip) from remote sources or registries;
• Integrity & Resume: Provides SHA-256 integrity verification, resumable downloads, and offline reuse;
• Self-Healing Isolation: Kept strictly separate from runtime extraction workspaces. Corrupted runtime directories can self-heal by re-extracting from cache, and cache archives can be safely purged on demand to reclaim disk space.

2. Extracted Extensions Root (~/.openarko/extensions/)

• Ready Runtime Directory: Stores all uncompressed, ready-to-use extension directories scanned and mounted directly by the host runtime;
• Aligned with node_modules Standards: Each extension resides in its own isolated directory (e.g. <extension-id>/ or @scope/<name>/);
• Standard Manifest: The root of each extension directory must contain a valid manifest.json (or extension.json) manifest, metadata, tool executables, and capability assets, preventing ad-hoc unmanifested scripts or host path pollution.

Dynamic Runtime Lifecycle (Zero-Restart Hot Reload)

The openarko runtime enforces a complete lifecycle state machine for extension plugins, executing transitions without restarting the host process:

• Dynamic Load: Parses the extension manifest and dynamically registers MCP tools, skill assets, and message/event channels in real time without downtime;
• Dynamic Unload: Instantly unregisters MCP tools, terminates active network connections and event listeners, and releases sandbox memory, preventing zombie listeners or hanging handles;
• Enable / Disable: Provides non-destructive toggling of capabilities without removing underlying disk files;
• Physical Removal: Performs safe unmounting followed by cascade deletion of the unpacked directory in ~/.openarko/extensions/ and cached packages in ~/.openarko/cache/.