Cortex SDK

The official Rust SDK for Cortex's trusted native plugin boundary.

This crate defines the public plugin surface with zero dependency on Cortex internals. The runtime loads trusted native plugins through a stable C-compatible ABI and bridges these traits to its own turn runtime, command surface, and transport layer.

Process-isolated JSON plugins do not need this crate. They are defined through manifest.toml plus a child-process command. Use cortex-sdk when you are building a trusted in-process native plugin that exports cortex_plugin_init.

SDK release cadence is independent from Cortex runtime releases. Choose the SDK version by the native ABI/DTO surface your plugin needs, not by the latest Cortex runtime patch. Runtime compatibility is declared in the plugin manifest.toml cortex_version field, which is the minimum Cortex runtime version the plugin supports.

Architecture

 ┌──────────────┐     dlopen      ┌──────────────────┐
 │ cortex-runtime│ ──────────────▶ │  your plugin.so  │
 │   (daemon)    │                 │  cortex-sdk only  │
 └──────┬───────┘   FFI call      └────────┬─────────┘
        │        cortex_plugin_init()         │
        ▼                                    ▼
   ToolRegistry  ◀─── register ───  MultiToolPlugin
                                    ├─ plugin_info()
                                    └─ create_tools()
                                        ├─ Tool A
                                        └─ Tool B

Plugins are compiled as cdylib shared libraries. The runtime calls cortex_plugin_init, receives a C-compatible function table, then asks that table for plugin metadata, tool descriptors, and tool execution results. Rust trait objects stay inside the plugin; they never cross the dynamic-library boundary.

The SDK exposes a runtime-aware execution surface:

[InvocationContext] gives tools stable metadata such as session id, canonical actor, transport/source, and foreground/background scope
[ToolRuntime] lets tools emit progress updates and observer text back to the parent turn
[ToolCapabilities] lets tools declare whether they emit runtime signals and whether they are background-safe
[Attachment] and [ToolResult::with_media] let tools return structured image, audio, video, or file outputs without depending on Cortex internals

Native Plugin Quick Start

Cargo.toml:

[package]
name = "cortex-plugin-native-hello"
version = "0.1.0"
edition = "2024"
publish = false

[lib]
crate-type = ["cdylib", "rlib"]

[dependencies]
cortex-sdk = "1.6.4"
serde_json = "1"

src/lib.rs:

use cortex_sdk::prelude::*;

#[derive(Default)]
struct MyPlugin;

impl MultiToolPlugin for MyPlugin {
    fn plugin_info(&self) -> PluginInfo {
        PluginInfo {
            name: "my-plugin".into(),
            version: env!("CARGO_PKG_VERSION").into(),
            description: "My custom tools for Cortex".into(),
        }
    }

    fn create_tools(&self) -> Vec<Box<dyn Tool>> {
        vec![Box::new(WordCountTool)]
    }
}

struct WordCountTool;

impl Tool for WordCountTool {
    fn name(&self) -> &'static str { "word_count" }

    fn description(&self) -> &'static str {
        "Count words in a text string. Use when the user asks for word \
         counts, statistics, or text length metrics."
    }

    fn input_schema(&self) -> serde_json::Value {
        serde_json::json!({
            "type": "object",
            "properties": {
                "text": {
                    "type": "string",
                    "description": "The text to count words in"
                }
            },
            "required": ["text"]
        })
    }

    fn execute(&self, input: serde_json::Value) -> Result<ToolResult, ToolError> {
        let text = input["text"]
            .as_str()
            .ok_or_else(|| ToolError::InvalidInput("missing 'text' field".into()))?;
        let count = text.split_whitespace().count();
        Ok(ToolResult::success(format!("{count} words")))
    }
}

cortex_sdk::export_plugin!(MyPlugin);

Tools that need runtime context can override [Tool::execute_with_runtime] instead of only [Tool::execute].

manifest.toml:

name = "native-hello"
version = "0.1.0"
description = "Example trusted native Cortex plugin"
cortex_version = "1.6.0"
trust = "trusted_native"

[capabilities]
provides = ["tools"]
secrets = false

[sandbox]
level = "trusted_in_process"

[native]
library = "lib/libcortex_plugin_native_hello.so"
isolation = "trusted_in_process"
abi_version = 1

Build, Sign, Pack, Publish

cargo build --release
cortex plugin review .
cortex plugin test .
cortex plugin keygen ~/.config/cortex/plugin-signing/example-dev.ed25519
cortex plugin sign . --key ~/.config/cortex/plugin-signing/example-dev.ed25519 --publisher example.dev
cortex plugin pack .
sha256sum cortex-plugin-native-hello-v0.1.0-linux-amd64.cpx > cortex-plugin-native-hello-v0.1.0-linux-amd64.cpx.sha256

Upload the .cpx and .sha256 files to a GitHub Release. Users install the package by repository name and restart the daemon so the native library is loaded:

cortex plugin install owner/cortex-plugin-native-hello@0.1.0
cortex restart

Installing or replacing a trusted native shared library still requires a daemon restart so the new code is loaded. Process-isolated plugin manifest changes hot-apply without that restart.

Plugin Lifecycle

Load — dlopen at daemon startup
Create — runtime calls export_plugin!-generated stable ABI init
Register — [MultiToolPlugin::create_tools] is called once; each [Tool] is registered in the global tool registry
Execute — the LLM invokes tools by name during turns; the runtime calls [Tool::execute] with JSON parameters
Retain — the library handle is held for the daemon's lifetime; Drop runs only at shutdown

Tool Design Guidelines