Skip to content

AgenticHighway/kelvinclaw

BranchesTags

Repository files navigation

kelvinclaw

KelvinClaw is a Secure, Stable, and Modular Runtime for Agentic 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

Choose the onboarding path for your experience level:

Canonical quick start commands:

scripts/quickstart.sh --mode local
scripts/quickstart.sh --mode docker

Verify a specific path:

scripts/verify-onboarding.sh --track beginner
scripts/verify-onboarding.sh --track rust
scripts/verify-onboarding.sh --track wasm
scripts/verify-onboarding.sh --track daily

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:

  • kelvin-host
  • kelvin-gateway
  • kelvin-memory-controller
  • kelvin-registry
  • top-level ./kelvin launcher

The release workflow produces:

  • linux-x86_64 and linux-arm64 tarballs
  • amd64 and arm64 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:

The intended Unix end-user entrypoint is:

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

On first run, ./kelvin fetches the official trust policy plus the required first-party plugins into ~/.kelvinclaw, then starts Kelvin. The currently bootstrapped first-party packages are:

  • kelvin.cli@0.1.1
  • kelvin.openai@0.1.1 when OPENAI_API_KEY is available

Additional published first-party model plugins can be installed explicitly from the plugin index, including kelvin.anthropic and kelvin.openrouter.

Windows bundles ship kelvin.cmd and kelvin.ps1 at the archive root. For manual validation without publishing a GitHub Release, run the Release Executables workflow with workflow_dispatch.

Release prerequisites:

  • curl
  • tar
  • awk
  • ca-certificates on minimal Linux images

OpenAI key options for the release launcher:

  • export OPENAI_API_KEY before running ./kelvin
  • put OPENAI_API_KEY=... in ./.env or ./.env.local
  • put OPENAI_API_KEY=... in ~/.kelvinclaw/.env or ~/.kelvinclaw/.env.local
  • if you run ./kelvin interactively with no key configured, Kelvin prompts once and uses the key for that run only

Validated public onboarding today:

  • Linux release bundles are validated end to end on fresh Ubuntu with curl and ca-certificates installed.
  • The no-args ./kelvin flow fetches trust metadata, installs official plugins, 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-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:

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-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:

Memory Backend Swapping

kelvin-memory::MemoryFactory supports:

  • Markdown
  • InMemoryVector
  • InMemoryWithMarkdownFallback

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

CLI Example

scripts/install-kelvin-cli-plugin.sh
KELVIN_PLUGIN_HOME=.kelvin/plugins \
KELVIN_TRUST_POLICY_PATH=.kelvin/trusted_publishers.json \
CARGO_TARGET_DIR=target/try-kelvin-cli cargo run -p kelvin-host -- --prompt "hello" --workspace /path/to/workspace --memory fallback

OpenAI provider path:

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

Anthropic provider status:

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:

scripts/try-kelvin.sh "hello"

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:

  • scripts/kelvin-gateway-daemon.sh start|stop|status|logs|health
  • scripts/kelvin-gateway-service.sh render-systemd-user|install-systemd-user|render-launchd|install-launchd
  • scripts/kelvin-gateway-service-run.sh
  • scripts/kelvin-local-profile.sh start|stop|status|doctor
  • scripts/quickstart.sh --mode local|docker
  • scripts/docker-cache-prune.sh [--dry-run]
  • scripts/kelvin-doctor.sh
  • scripts/kelvin-webchat.sh [port]

kelvin-doctor and gateway --doctor output machine-readable checks with remediation hints.

Runtime Container (No Rust Toolchain Required)

For end users, run the minimal runtime container and complete first-time setup interactively:

scripts/run-runtime-container.sh

This opens a setup wizard in-container, installs required plugins from the remote plugin index, and prepares a persistent runtime home under .kelvin/.

After setup:

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

Reference docs:

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
scripts/remote-test.sh --docker

Additional variants:

REMOTE_TEST_HOST=your-user@your-host scripts/remote-test.sh
REMOTE_TEST_REMOTE_DIR=~/work/kelvinclaw scripts/remote-test.sh --native
scripts/remote-test.sh --docker
scripts/remote-test.sh --host your-user@your-host --cargo-args '-- --nocapture'

Notes:

  • .env and .env.local are gitignored; keep personal hosts/IPs there only.
  • scripts/remote-test.sh reads REMOTE_TEST_HOST, REMOTE_TEST_REMOTE_DIR, and REMOTE_TEST_DOCKER_IMAGE from .env/.env.local.
  • .env files are parsed as key/value data and are not executed as shell code.

Plugin Install (No Build Required)

Install Kelvin's first-party CLI plugin package:

scripts/install-kelvin-cli-plugin.sh

Install optional browser automation plugin profile:

scripts/install-kelvin-browser-plugin.sh

Default index:

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

Install a prebuilt plugin package:

scripts/plugin-install.sh --package ./dist/acme.echo-1.0.0.tar.gz

List installed plugins:

scripts/plugin-list.sh
scripts/plugin-list.sh --json

Uninstall plugin:

scripts/plugin-uninstall.sh --id acme.echo --version 1.0.0
scripts/plugin-uninstall.sh --id acme.echo --purge

Run installer tests:

scripts/test-plugin-install.sh
scripts/test-cli-plugin-integration.sh

Plugin discovery:

scripts/plugin-discovery.sh
scripts/plugin-discovery.sh --plugin kelvin.cli
scripts/plugin-update-check.sh --json

Hosted registry service:

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

scripts/plugin-discovery.sh --registry-url http://127.0.0.1:34718
scripts/plugin-update-check.sh --registry-url http://127.0.0.1:34718 --json

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:

AWS_PROFILE=ah-willsarg-iam scripts/plugin-sign.sh \
  --manifest ~/.kelvinclaw/plugins/acme.echo/1.0.0/plugin.json \
  --kms-key-id alias/ah/kelvin/plugins/prod \
  --kms-region us-east-1 \
  --publisher-id acme \
  --trust-policy-out ./trusted_publishers.acme.json

PEM signing remains supported for community publishers and local development:

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

Trust policy operations:

scripts/plugin-trust.sh show
scripts/plugin-trust.sh rotate-key --publisher acme --public-key <base64>
scripts/plugin-trust.sh revoke --publisher acme
scripts/plugin-trust.sh pin --plugin acme.echo --publisher acme

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:

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:

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:

scripts/test-sdk.sh

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

About

A Security focused, Stable, Reliable, Modular, Claw.

Topics

plugin rust modular skills wasm crate claw openclaw picoclaw zeroclaw ironclaw

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

6 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases 7

v0.1.8 Latest
Mar 15, 2026
+ 6 releases

Packages

 
 
 

Contributors 3

Languages