Cortex SDK

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

cortex-sdk lets Rust plugin authors implement Tool and MultiToolPlugin while exporting Cortex's stable native ABI. The daemon loads a C-compatible function table through cortex_plugin_init; Rust trait objects stay inside the plugin library.

Process-isolated JSON plugins do not need this crate. They are declared entirely through manifest.toml and a child-process command. Use cortex-sdk when you are building a trusted in-process native plugin.

Supported Plugin Boundaries

Cortex has two public plugin boundaries:

Process JSON — child-process tools declared in manifest.toml, using stdin/stdout JSON. This is the default boundary for third-party and cross-language plugins and does not require the SDK.
Stable native ABI — trusted in-process shared libraries that export cortex_plugin_init. cortex-sdk is the Rust facade for that ABI.

Add The Crate

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

Process JSON Scaffold

Use the process JSON boundary when you do not need in-process latency or host callbacks:

cortex --new-process-plugin hello
cd cortex-plugin-hello

The generated project contains:

cortex-plugin-hello/
├── manifest.toml
├── bin/
│   └── hello-tool
├── skills/
├── prompts/
└── README.md

Manifest

name = "hello"
version = "0.1.0"
description = "Example process-isolated Cortex plugin"
cortex_version = "1.2.0"

[capabilities]
provides = ["tools", "skills"]

[native]
isolation = "process"

[[native.tools]]
name = "word_count"
description = "Count words in text using a child process."
command = "bin/word-count"
inherit_env = ["PATH"]
timeout_secs = 5
max_output_bytes = 1048576
max_memory_bytes = 67108864
max_cpu_secs = 2
input_schema = { type = "object", properties = { text = { type = "string" } }, required = ["text"] }

Protocol

Cortex sends:

{"tool":"word_count","input":{"text":"hello world"}}

The process returns:

{"output":"2","is_error":false}

Use is_error = true for command-level failures that should be visible as failed tool calls.

Packaging

cargo build --release
cortex plugin pack .
cortex plugin install ./cortex-plugin-hello-v0.1.0-linux-amd64.cpx
cortex restart

Folder installs are supported too:

cargo build --release
cortex plugin install ./cortex-plugin-hello/
cortex restart

When you install from a local plugin directory, Cortex copies only plugin assets (manifest.toml, lib/, skills/, prompts/). If lib/ is missing but the manifest declares [native].library, the installer automatically copies the built shared library from target/release/ (or target/debug/) into the installed plugin lib/ directory.

Structured Media

Tool output can include structured media by returning the SDK ToolResult shape from a host language binding or by emitting compatible JSON. Media attachments are delivered by Cortex transports independently from the text returned to the model.

Native ABI Manifest

Trusted native plugins declare the stable native boundary explicitly:

name = "dev"
version = "1.2.0"
description = "Trusted native development tools"
cortex_version = "1.2.0"

[capabilities]
provides = ["tools", "skills"]

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

The runtime does not load legacy Rust trait-object symbols. Native plugins must export cortex_plugin_init, which cortex_sdk::export_plugin! generates.

Documentation

API docs: https://docs.rs/cortex-sdk
Runtime/plugin guide: https://github.com/by-scott/cortex/blob/main/docs/plugins.md

cortex-sdk 1.2.0