kelvinclaw

KelvinClaw is a Secure, Stable, and Modular Harness for Agentic AI Workflows. It focuses on predictable runtime behavior, policy-driven extension loading, and a maintainable SDK surface for plugin developers.

SDK name: Kelvin Core.

What this project includes:

• control plane (kelvin root + brain): policy, orchestration, lifecycle
• data plane (kelvin-memory-controller): RPC memory operations with security checks
• SDK (Kelvin Core): stable interfaces for plugins, tools, and runtime integration
• plugin system: signed package install/verification and policy-based capability enforcement

For end users, plugins are installed as packages and executed by Kelvin. They do not need to compile the Rust workspace.

Getting Started

Quick Try (Docker, no API keys needed)

cp .env.example .env                                # uses kelvin.echo model provider by default
docker compose up -d                                # starts gateway + init
docker compose --profile tui run --rm kelvin-tui    # interactive TUI

This runs the built-in echo provider — no OpenAI/Anthropic key required. To use a real LLM, edit .env and set KELVIN_MODEL_PROVIDER + your API key.

KELVIN_MODEL_PROVIDER=kelvin.anthropic              # e.g. anthropic
ANTHROPIC_API_KEY=sk-ant-your-api-key-here

Quick Try (local Rust)

cargo run -p kelvin-host -- --prompt "hello kelvin" --memory fallback

Install via Homebrew

brew tap AgenticHighway/tap
brew install kelvinclaw
kelvin init
kelvin

Homebrew and release installs now treat ~/.kelvinclaw/.env as the canonical config path. On the first interactive kelvin launch, Kelvin asks whether you want CLI chat or the TUI app, remembers that choice in ~/.kelvinclaw/preferences.env, and routes future kelvin launches there by default. Run kelvin /help to print the interactive quickstart from the shell.

More Options

Choose the onboarding path for your experience level:

• docs/GETTING_STARTED.md
• latest public release: GitHub Releases

See docs/getting-started/GETTING_STARTED.md for track-specific setup guides.

Plugin authors who prefer Docker over local Rust setup should use the official Rust Bookworm image through:

scripts/plugin-author-docker.sh -- bash

Release Executables

Tagged releases publish executable bundles for all major platforms.

The release workflow produces:

• linux-x86_64 and linux-arm64 tarballs + Debian packages
• macos-x86_64 and macos-arm64 tarballs
• windows-x86_64 zip bundles
• matching SHA-256 files for every artifact

Linux and Windows builds run on Blacksmith runners. macOS builds run on GitHub-hosted macOS runners. macOS artifacts are intentionally unsigned and unnotarized in this phase.

Latest public release:

• GitHub Releases

Tagged releases also refresh the Homebrew tap formula in AgenticHighway/homebrew-tap when the HOMEBREW_TAP_TOKEN repository secret is configured.

End-user install (Unix)

curl -sSL https://raw.githubusercontent.com/AgenticHighway/kelvinclaw/main/install.sh | bash
# Add the install directory to PATH, then:
./bin/kelvin init    # interactive first-run setup
./bin/kelvin         # choose CLI chat or TUI on first run

Or from a downloaded tarball:

tar -xzf kelvinclaw-<version>-linux-<arch>.tar.gz
cd kelvinclaw-<version>-linux-<arch>
./bin/kelvin init
./bin/kelvin

kelvin init writes ~/.kelvinclaw/.env, generates auth keys, and writes a permissive trust policy. After that, the first interactive bare kelvin launch asks whether you want CLI chat or the TUI app, remembers that choice in ~/.kelvinclaw/preferences.env, and launches the selected experience. The CLI chat path bootstraps kelvin.cli plus the configured model provider before opening kelvin-host; the TUI path starts the gateway and memory controller as needed before opening kelvin-tui. Pass kelvin init --with-completions to install shell completions during setup, or use kelvin completions <shell> --write later.

Add bin/ to your PATH to use kelvin without a prefix. The examples below assume this is done:

export PATH="/path/to/kelvinclaw-<version>-<platform>/bin:$PATH"

Plugin management from the release bundle:

kelvin plugin install kelvin.anthropic
kelvin plugin install kelvin.openrouter
kelvin plugin list
kelvin plugin update

Gateway lifecycle:

kelvin gateway start
kelvin gateway start --foreground
kelvin gateway status
kelvin gateway stop
kelvin gateway restart
kelvin gateway start -- --bind 0.0.0.0:34617

System service (optional):

kelvin service install-systemd     # systemd user unit
kelvin service install-launchd     # launchd plist (macOS)

Diagnostics:

kelvin /help           # print the interactive quickstart from the shell
kelvin medkit          # offline checks — env, keys, plugins, daemons
kelvin medkit --fix    # attempt automatic repairs
kelvin doctor          # live WebSocket probe of running gateway

.env load order (first match per key wins):

1. ~/.kelvinclaw/.env.local
2. ~/.kelvinclaw/.env
3. ./.env.local
4. ./.env

Variables already in the process environment are never overwritten.

Validated public onboarding:

• Linux release bundles are validated end to end on fresh Ubuntu.
• The kelvin init + kelvin flow installs required plugins from the official index and completes a real OpenAI-backed run when OPENAI_API_KEY is configured.
• macOS and Windows artifacts are published from CI, but the fully documented and validated public onboarding path today is Linux-first.

Repository Layout

• apps/kelvin-cli: unified kelvin binary (start, stop, init, gateway, plugin, medkit, doctor, …)
• apps/kelvin-host: thin trusted host executable
• apps/kelvin-gateway: secure WebSocket control-plane gateway
• crates/*: core contracts, runtime, SDK, memory API/client/controller, and execution engine
• first-party plugin distribution repo: agentichighway/kelvinclaw-plugins
• examples/: sample source crates for developers

Architecture

See:

• OVERVIEW.md
• docs/architecture.md
• docs/gateway-protocol.md
• docs/GETTING_STARTED.md
• docs/kelvin-gap-analysis.md
• docs/KELVIN_CORE_SDK.md
• docs/SDK_TEST_MATRIX.md
• docs/SDK_OWASP_TOP10_AI_2025.md
• docs/SDK_NIST_AI_RMF_1_0.md
• docs/PLUGIN_INSTALL_FLOW.md
• docs/ROOT_VS_SDK.md
• docs/CORE_ADMISSION_POLICY.md
• docs/SDK_PRINCIPLES.md
• docs/trusted-executive-wasm.md
• docs/RUST_DEVELOPER_QUICKSTART.md
• docs/memory-control-data-plane.md
• docs/memory-rpc-contract.md
• docs/memory-module-sdk.md
• docs/memory-controller-deployment-profiles.md
• docs/model-plugin-abi.md
• docs/channel-plugin-abi.md
• docs/openai-plugin-install-and-run.md
• docs/anthropic-plugin-install-and-run.md
• docs/openrouter-plugin-install-and-run.md
• docs/runtime-container-first-run.md
• docs/plugin-index-schema.md
• docs/toolpack-sdk-plugins.md
• docs/plugin-author-kit.md
• docs/plugin-quality-tiers.md
• docs/plugin-trust-operations.md
• docs/agents-tradeoffs.md
• docs/compatibility-contracts.md

Workspace crates:

• crates/kelvin-core: contracts and shared types
• crates/kelvin-memory-api: protobuf and gRPC service contracts
• crates/kelvin-memory-client: root-side RPC adapter implementing MemorySearchManager
• crates/kelvin-memory-controller: memory data plane gRPC server + WASM execution policy
• crates/kelvin-memory-module-sdk: memory module ABI helpers and WIT contract
• crates/kelvin-memory: in-process memory backends used by local/test compositions
• crates/kelvin-brain: agent loop orchestration
• crates/kelvin-wasm: trusted native executive for untrusted WASM skills

Apps:

• apps/kelvin-cli: unified CLI binary (kelvin)
• apps/kelvin-host: thin host executable for Kelvin SDK
• apps/kelvin-gateway: WebSocket gateway over SDK runtime

Interface-First Design

Main traits:

• Brain
• MemorySearchManager
• ModelProvider
• SessionStore
• Tool / ToolRegistry
• EventSink
• PluginFactory / PluginRegistry (Kelvin Core SDK)
• CoreRuntime / RunRegistry (core lifecycle state machine)

Everything in the runtime is composed with trait objects so concrete implementations can be swapped.

SDK Runtime Integration

The runtime integrates through the Kelvin Core SDK path:

• WasmSkillPlugin (plugin manifest + tool factory)
• InMemoryPluginRegistry (policy-gated registration)
• SdkToolRegistry (validated tool projection for runtime wiring)
• SdkModelProviderRegistry (validated model-provider projection)
• kelvin_cli (CLI plugin executed before each run)
• kelvin.openai (first-party OpenAI model plugin, optional)
• kelvin.anthropic (first-party Anthropic model plugin)
• kelvin.openrouter (first-party OpenRouter model plugin)
• Kelvin Core tool-pack plugins (fs_safe_read, fs_safe_write, web_fetch_safe, schedule_cron, session_tools)

Trusted Executive + Untrusted Skills

Kelvin now supports the split model:

• trusted native Rust host (kelvin-wasm) with system keys
• untrusted WASM skills loaded at runtime
• explicit host ABIs (claw::* for tools, kelvin_model_host_v1 for model providers)
• sandbox policy gates that deny disallowed capabilities at module instantiation

Key types in kelvin-wasm:

• WasmSkillHost
• SandboxPolicy
• ClawCall
• SandboxPreset

Run a .wasm skill with the native executive:

cargo run -p kelvin-wasm --bin kelvin-wasm-runner -- --wasm path/to/skill.wasm --policy-preset locked_down

Model-provider ABI reference:

• docs/model-plugin-abi.md

Memory Backend Swapping

kelvin-memory::MemoryFactory supports:

• Markdown
• InMemoryVector
• InMemoryWithMarkdownFallback

The fallback manager mimics KelvinClaw's primary->fallback behavior.

CLI Example

kelvin plugin install kelvin.cli
KELVIN_PLUGIN_HOME=~/.kelvinclaw/plugins \
KELVIN_TRUST_POLICY_PATH=~/.kelvinclaw/trusted_publishers.json \
cargo run -p kelvin-host -- --prompt "hello" --workspace /path/to/workspace --memory fallback

OpenAI provider path:

kelvin plugin install kelvin.openai
OPENAI_API_KEY=<your_key> \
KELVIN_PLUGIN_HOME=~/.kelvinclaw/plugins \
KELVIN_TRUST_POLICY_PATH=~/.kelvinclaw/trusted_publishers.json \
cargo run -p kelvin-host -- --prompt "hello" --model-provider kelvin.openai --workspace /path/to/workspace --memory fallback

Anthropic provider:

• see docs/anthropic-plugin-install-and-run.md

The CLI executable is only a thin launcher. Runtime behavior is composed in kelvin-sdk, and the CLI path executes through an installed plugin (kelvin_cli) loaded through the same secure installed-plugin path as third-party plugins.

Quick run:

cargo run -p kelvin-host -- --prompt "hello" --memory fallback

Interactive mode:

cargo run -p kelvin-host -- --interactive --workspace /path/to/workspace --state-dir /path/to/workspace/.kelvin/state

Gateway Example

Run the gateway with connect-token auth:

KELVIN_GATEWAY_TOKEN=change-me \
CARGO_TARGET_DIR=target/try-kelvin-gateway cargo run -p kelvin-gateway -- \
  --bind 127.0.0.1:34617 \
  --workspace /path/to/workspace

Optional direct platform ingress can run on a separate HTTP listener:

KELVIN_GATEWAY_TOKEN=change-me \
KELVIN_GATEWAY_INGRESS_BIND=127.0.0.1:34618 \
KELVIN_TELEGRAM_WEBHOOK_SECRET_TOKEN=telegram-secret \
KELVIN_SLACK_SIGNING_SECRET=slack-signing-secret \
KELVIN_DISCORD_INTERACTIONS_PUBLIC_KEY=<hex-public-key> \
CARGO_TARGET_DIR=target/try-kelvin-gateway cargo run -p kelvin-gateway -- \
  --bind 127.0.0.1:34617 \
  --workspace /path/to/workspace

Direct ingress routes:

• POST /ingress/telegram
• POST /ingress/slack
• POST /ingress/discord

Operator console on the same HTTP listener:

• GET /operator/

Methods available over the socket:

• connect
• health
• agent / run.submit
• agent.wait / run.wait
• agent.state / run.state
• agent.outcome / run.outcome
• channel.telegram.ingest
• channel.telegram.pair.approve
• channel.telegram.status
• channel.slack.ingest
• channel.slack.status
• channel.discord.ingest
• channel.discord.status
• channel.route.inspect
• operator.runs.list
• operator.sessions.list
• operator.session.get
• operator.plugins.inspect
• schedule.list
• schedule.history

Operational scripts (dev / CI):

• scripts/kelvin-dev-stack.sh start|stop|status|doctor
• scripts/docker-cache-prune.sh [--dry-run]

For end-user stack management use the kelvin CLI (kelvin start, kelvin stop, kelvin gateway, kelvin medkit, kelvin doctor).

Runtime Container (No Rust Toolchain Required)

For end users, run KelvinClaw via Docker Compose:

cp .env.example .env
docker compose up -d

The init container installs required plugins automatically and prepares a persistent runtime home on the kelvin-home volume.

After setup:

kelvin-host --prompt "What is KelvinClaw?" --timeout-ms 3000

Reference docs:

• docs/runtime-container-first-run.md
• docs/plugin-index-schema.md

Tool-trigger pattern for the default model provider:

[[tool:time]]
[[tool:hello_tool {"foo":"bar"}]]

Remote Build and Test (Optional)

Remote testing is optional. Public clones can run local Docker tests without any private host setup.

Privacy-conscious remote setup:

cp .env.example .env
$EDITOR .env

Notes:

• .env and .env.local are gitignored; keep personal hosts/IPs there only.
• .env files are parsed as key/value data and are not executed as shell code.

Plugin Management

Plugin operations are handled by the kelvin CLI:

kelvin plugin install kelvin.cli
kelvin plugin install --package ./dist/acme.echo-1.0.0.tar.gz
kelvin plugin list
kelvin plugin status
kelvin plugin search <query>
kelvin plugin info <plugin-id>
kelvin plugin update
kelvin plugin uninstall acme.echo --yes

Default index:

• https://raw.githubusercontent.com/agentichighway/kelvinclaw-plugins/main/index.json

Override with KELVIN_PLUGIN_INDEX_URL.

Hosted registry service:

cargo run -p kelvin-registry -- \
  --index ./index.json \
  --bind 127.0.0.1:34619

Installed Plugin Runtime (Secure Loader)

kelvin-brain can load installed SDK plugin packages and project them into runtime tool/model providers with policy enforcement:

• signed manifest verification (plugin.sig, Ed25519 trusted publishers)
• manifest integrity validation (entrypoint_sha256)
• capability scopes (fs_read_paths, network_allow_hosts)
• operational controls (timeout, retries, rate limit, circuit breaker)
• runtime kind checks (wasm_tool_v1, wasm_model_v1)
• model-plugin import allowlist checks (kelvin_model_host_v1 imports only)

Source: crates/kelvin-brain/src/installed_plugins.rs

Default boot helpers:

• load_installed_plugins_default(core_version, security_policy)
• load_installed_tool_plugins_default(core_version, security_policy)
• default_plugin_home()
• default_trust_policy_path()

Default paths:

• plugin home: ~/.kelvinclaw/plugins (or KELVIN_PLUGIN_HOME)
• trust policy: ~/.kelvinclaw/trusted_publishers.json (or KELVIN_TRUST_POLICY_PATH)

Publisher Signing

Sign a package manifest and generate plugin.sig:

scripts/plugin-sign.sh \
  --manifest ~/.kelvinclaw/plugins/acme.echo/1.0.0/plugin.json \
  --private-key ~/.kelvinclaw/keys/acme-ed25519-private.pem \
  --publisher-id acme \
  --trust-policy-out ./trusted_publishers.acme.json

KMS-backed signing is also supported for first-party releases (see internal runbook).

Trust policy is stored at ~/.kelvinclaw/trusted_publishers.json. The kelvin plugin install command merges publisher public keys from the index entry's trust_policy_url automatically. Edit the file directly for manual trust operations; see trusted_publishers.example.json for the schema.

GitHub Actions automation:

• .github/workflows/memory-kms-smoke.yml runs the live AWS KMS memory signer roundtrip through GitHub OIDC on a Blacksmith runner.

Plugin author workflow (uses scripts/kelvin-plugin-dev.sh):

export PATH="$PWD/scripts:$PATH"
kelvin-plugin new --id acme.echo --name "Acme Echo" --runtime wasm_tool_v1
kelvin-plugin test --manifest ./plugin-acme.echo/plugin.json
kelvin-plugin pack --manifest ./plugin-acme.echo/plugin.json
kelvin plugin install --package ./plugin-acme.echo/dist/acme.echo-0.1.0.tar.gz
kelvin plugin verify --package ./plugin-acme.echo/dist/acme.echo-0.1.0.tar.gz

Model-plugin author workflow:

export PATH="$PWD/scripts:$PATH"
kelvin-plugin new --id acme.anthropic --name "Acme Anthropic" --runtime wasm_model_v1 --provider-profile anthropic.messages
cd ./plugin-acme.anthropic
./build.sh
kelvin-plugin test --manifest ./plugin.json
kelvin-plugin pack --manifest ./plugin.json
kelvin plugin install --package ./dist/acme.anthropic-0.1.0.tar.gz
kelvin plugin verify --package ./dist/acme.anthropic-0.1.0.tar.gz
kelvin-plugin smoke --manifest ./plugin.json

Community/local plugins can stay unsigned_local. Kelvin warns on install, but still allows them to load from a local plugin home.

For declarative providers on the OpenAI-compatible chat-completions family:

kelvin plugin new \
  --id acme.openrouter \
  --name "Acme OpenRouter" \
  --runtime wasm_model_v1 \
  --provider-name openrouter \
  --provider-profile openrouter.chat \
  --protocol-family openai_chat_completions \
  --api-key-env OPENROUTER_API_KEY \
  --base-url-env OPENROUTER_BASE_URL \
  --default-base-url https://openrouter.ai/api/v1 \
  --endpoint-path chat/completions \
  --allow-host openrouter.ai \
  --model-name openai/gpt-4.1-mini

Authoring docs:

• docs/plugins/plugin-author-kit.md
• docs/plugins/build-a-model-plugin.md

Trust policy template:

• trusted_publishers.example.json

Host boot behavior:

• apps/kelvin-host calls kelvin_sdk::run_with_sdk(...) only.
• kelvin-sdk requires installed kelvin_cli and auto-loads installed SDK plugins with load_installed_plugins_default(...).

Local Test

cargo test --workspace

SDK certification lane:

cargo test -p kelvin-sdk

Docker:

scripts/test-docker.sh

Clean rebuild from zero (recommended before final pushes):

scripts/test-docker.sh --final

Build the sample Rust WASM skill:

cargo build --target wasm32-unknown-unknown --manifest-path examples/echo-wasm-skill/Cargo.toml

Run the sample skill:

cargo run -p kelvin-wasm --bin kelvin-wasm-runner -- --wasm examples/echo-wasm-skill/target/wasm32-unknown-unknown/debug/echo_wasm_skill.wasm