RustyHand

The Agent Operating System

Open-source Agent OS built in Rust. 134K LOC. 10 crates. 3,000+ tests. Zero clippy warnings.
One binary. Battle-tested. Agents that actually work for you.

Quick Start • CLI Reference • API Docs

v0.1.0 — First Public Release (April 2026)

RustyHand is feature-complete but this is the first public release. You may encounter rough edges or breaking changes between minor versions. Pin to a specific commit for production use until v1.0. Report issues here.

Origin

This project is based on OpenFang by RightNow-AI, modified and extended for custom use cases.

Table of Contents

• What is RustyHand?
• Installation
• Quick Start
• Configuration
• CLI Reference
• Autonomous Templates
• 37 Pre-built Agent Templates
• 37 Channel Adapters
• 26 LLM Providers — 130+ Models
• Architecture
• API Endpoints
• Dashboard
• Security
• Deployment
• Development
• Benchmarks
• MCP Integration (for AI Agents)
• How It Works — Data Flow
• License

What is RustyHand?

RustyHand is an open-source Agent Operating System — not a chatbot framework, not a Python wrapper around an LLM. It is a full operating system for autonomous agents, built from scratch in Rust.

Traditional agent frameworks wait for you to type something. RustyHand runs autonomous agents that work for you — on schedules, 24/7, building knowledge graphs, monitoring targets, generating leads, managing social media, and reporting results to your dashboard.

The entire system compiles to a single ~32MB binary. One install, one command, your agents are live.

Installation

One-liner (Linux / macOS / WSL)

curl -fsSL https://raw.githubusercontent.com/ginkida/rustyhand/main/scripts/install.sh | sh

Environment variables:

• RUSTY_HAND_INSTALL_DIR — custom install path (default: ~/.rustyhand/bin)
• RUSTY_HAND_VERSION — pin a specific version tag

Windows (PowerShell)

irm https://raw.githubusercontent.com/ginkida/rustyhand/main/scripts/install.ps1 | iex

From source

git clone https://github.com/ginkida/rustyhand.git
cd rustyhand
cargo build --release -p rusty-hand-cli
# Binary: target/release/rustyhand (or rustyhand.exe on Windows)

Requires Rust 1.75+ (stable). The rust-toolchain.toml in the repo will auto-select the right toolchain.

Docker

docker compose up --build
# Dashboard at http://localhost:4200

Or build manually:

docker build -t rustyhand .
docker run -p 4200:4200 \
  -e MINIMAX_API_KEY=your-key \
  -v rustyhand-data:/data \
  rustyhand

Quick Start

# 1. Initialize — creates ~/.rustyhand/ and walks you through provider setup
rustyhand init

# 2. Start the daemon (API + kernel)
rustyhand start
# Dashboard is live at http://localhost:4200

# 3. Chat with the default agent
rustyhand chat

# 4. Spawn a pre-built agent
rustyhand agent new coder

# 5. Create an autonomous agent from the dashboard
# Open http://localhost:4200 → Agents → Templates → choose an autonomous template

# 6. Send a one-shot message
rustyhand message researcher "What are the emerging trends in AI agent frameworks?"

# 7. Launch the interactive TUI dashboard
rustyhand tui

# 8. Run diagnostics
rustyhand doctor

Configuration

Config file

Location: ~/.rustyhand/config.toml

# API server settings
api_key = "your-bearer-token"          # Recommended for non-localhost access
api_listen = "127.0.0.1:4200"          # HTTP bind address

[default_model]
provider = "minimax"                   # minimax, anthropic, gemini, openai, groq, ollama, etc.
model = "MiniMax-M2.7"                 # Model identifier (or MiniMax-M2.7-highspeed)
api_key_env = "MINIMAX_API_KEY"        # Env var holding the API key
# base_url = "https://api.minimax.io/v1"  # Optional: override endpoint

[memory]
decay_rate = 0.05                      # Memory confidence decay
# sqlite_path = "~/.rustyhand/data/rustyhand.db"

[network]
listen_addr = "127.0.0.1:4200"        # RHP P2P listen address
# shared_secret = ""                  # Required for P2P authentication

# Session compaction (LLM-based context management)
[compaction]
threshold = 80                         # Compact when messages exceed this count
keep_recent = 20                       # Keep this many recent messages
max_summary_tokens = 1024

# Usage display in chat responses
# usage_footer = "Full"               # Off, Tokens, Cost, Full

# Channel adapters (tokens via env vars)
[telegram]
bot_token_env = "TELEGRAM_BOT_TOKEN"
allowed_users = []                     # Empty = allow all

[discord]
bot_token_env = "DISCORD_BOT_TOKEN"
# guild_ids = []

[slack]
bot_token_env = "SLACK_BOT_TOKEN"
app_token_env = "SLACK_APP_TOKEN"

# MCP server connections
[[mcp_servers]]
name = "filesystem"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

Environment variables

Copy .env.example to ~/.rustyhand/.env and fill in the keys you need:

# LLM providers (set the ones you use)
MINIMAX_API_KEY=eyJ...             # MiniMax M2.7 ($0.30/M input — recommended)
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GROQ_API_KEY=gsk_...
DEEPSEEK_API_KEY=sk-...

# Local LLM providers (no key needed)
OLLAMA_BASE_URL=http://localhost:11434
VLLM_BASE_URL=http://localhost:8000
LMSTUDIO_BASE_URL=http://localhost:1234

# Channel tokens
TELEGRAM_BOT_TOKEN=123456:ABC-...
DISCORD_BOT_TOKEN=...
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...

# Log level
RUST_LOG=info
# RUST_LOG=rusty_hand=debug            # Debug RustyHand only

Manage config from the CLI

rustyhand config show                              # Print current config
rustyhand config edit                              # Open in $EDITOR
rustyhand config get default_model.provider        # Read a key
rustyhand config set default_model.provider groq   # Write a key
rustyhand config set-key groq                      # Interactively save API key
rustyhand config test-key groq                     # Verify connectivity

CLI Reference

Core commands

Agents

Channels

Models

Skills

Workflows & scheduling

Integrations (MCP)

Security & vault

Other

All list/status commands support --json for scripting.

Autonomous Templates

RustyHand ships autonomous templates as agent presets in the dashboard. They are not a separate runtime entity: each template creates a normal agent, and you can optionally attach a cron schedule during creation.

Each autonomous template bundles:

• Agent preset — model, profile, prompt, and capabilities
• Schedule defaults — suggested cron expression and trigger message
• Operational playbook — multi-phase prompt for recurring work
• Guardrails — approval and tool constraints where needed

Bundled Autonomous Templates

Use the dashboard to launch one: Agents → Templates or Create Agent → enable schedule.

37 Pre-built Agent Templates

Spawn any template with rustyhand agent new <name>:

Agent manifest format (agent.toml)

name = "hello-world"
version = "0.1.0"
description = "A friendly greeting agent"
author = "rusty-hand"
module = "builtin:chat"

[model]
provider = "groq"
model = "llama-3.3-70b-versatile"
max_tokens = 4096
temperature = 0.6
system_prompt = """Your system prompt here..."""

[resources]
max_llm_tokens_per_hour = 100000

[capabilities]
tools = ["file_read", "file_list", "web_fetch", "web_search", "memory_store", "memory_recall"]
network = ["*"]
memory_read = ["*"]
memory_write = ["self.*"]
agent_spawn = false

37 Channel Adapters

Connect agents to every platform your users are on. Each adapter supports per-channel model overrides, DM/group policies, rate limiting, and output formatting.

Core: Telegram, Discord, Slack, WhatsApp, Signal, Matrix
Enterprise: Microsoft Teams, Mattermost, Google Chat, Webex, Feishu/Lark, Zulip
Social: LINE, Viber, Facebook Messenger, Mastodon, Bluesky, Reddit, LinkedIn, Twitch
Community: IRC, Guilded, Revolt, Keybase, Discourse, Gitter, Rocket.Chat
Privacy: Threema, Mumble, Nextcloud Talk, Ntfy, Gotify
Workplace: Pumble, Flock, Twist, DingTalk, Webhooks

Channel policies

Each channel supports fine-grained control in config.toml:

[telegram]
bot_token_env = "TELEGRAM_BOT_TOKEN"
allowed_users = [123456789]            # Restrict to specific users
dm_policy = "Respond"                  # Respond | AllowedOnly | Ignore
group_policy = "MentionOnly"           # All | MentionOnly | CommandsOnly | Ignore
output_format = "TelegramHtml"         # Markdown | TelegramHtml | SlackMrkdwn | PlainText

26 LLM Providers — 130+ Models

3 native drivers (Anthropic, Gemini, OpenAI-compatible) route to 26 providers:

Cloud: Anthropic, OpenAI, Gemini, Groq, DeepSeek, OpenRouter, Together, Mistral, Fireworks, Cohere, Perplexity, xAI, AI21, Cerebras, SambaNova, HuggingFace, Replicate, Qwen, MiniMax, Zhipu, Moonshot, Qianfan, Copilot
Local: Ollama, vLLM, LM Studio

Features:

• Intelligent routing with task complexity scoring
• Automatic fallback between providers
• Per-model pricing and cost tracking
• Per-agent budget limits

Embedding providers

Vector embeddings power semantic memory recall. Auto-detected at boot (first available wins):

Configure explicitly in config.toml:

[memory]
embedding_provider = "voyage"              # or "openai", "ollama", etc.
embedding_api_key_env = "VOYAGE_API_KEY"

Or let RustyHand auto-detect: it probes Voyage → OpenAI → Ollama at boot and uses the first available provider. Falls back to text search (SQLite LIKE) when no embedding driver is found.

rustyhand models list                 # Browse all models
rustyhand models list --provider groq # Filter by provider
rustyhand models set claude-sonnet    # Set default model

Architecture

10 Rust crates with a modular kernel design:

rusty-hand-types       Core types, traits, config, taint tracking, Ed25519 manifest signing
    |
    +-- rusty-hand-memory      SQLite persistence, vector embeddings (Voyage/OpenAI/Ollama), session compaction
    +-- rusty-hand-wire        RHP P2P protocol (JSON-RPC over TCP, HMAC-SHA256 auth)
    +-- rusty-hand-channels    37 messaging adapters with rate limiting
    +-- rusty-hand-skills      Skill system + ClawHub marketplace
    +-- rusty-hand-extensions  25 MCP integrations, AES-256-GCM credential vault, OAuth2
    |
    +-- rusty-hand-runtime     Agent loop, 3 LLM drivers, 53+ tools, WASM sandbox, MCP, A2A
    |
    +-- rusty-hand-kernel      Orchestration: lifecycle, scheduling, metering, RBAC, workflows
    |
    +-- rusty-hand-api         Axum HTTP daemon, 120+ endpoints, WebSocket, SSE, OpenAI-compat
    |
    +-- rusty-hand-cli         CLI binary + TUI dashboard (ratatui)

Key internals

API Endpoints

Default: http://127.0.0.1:4200. All endpoints return JSON. Authenticate with Authorization: Bearer <api_key> when api_key is set in config.

Health & status

Agents

Budget

Network & P2P

A2A (Agent-to-Agent)

OpenAI-compatible

Drop-in replacement for OpenAI API:

curl -X POST http://localhost:4200/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "researcher",
    "messages": [{"role": "user", "content": "Analyze Q4 market trends"}],
    "stream": true
  }'

Full REST/WS/SSE endpoints cover agents, memory, workflows, channels, models, skills, sessions, approvals, triggers, crons, security, and more (120+ total).

Dashboard

The web dashboard is served at http://localhost:4200 when the daemon is running. Built with Alpine.js — no build step, no node_modules.

Sections

Connects via WebSocket with HTTP fallback. Supports dark/light/system themes.

Security

16 independent security layers — defense in depth, no single point of failure.

Deployment

Systemd

A service file is provided in deploy/rustyhand.service:

sudo cp deploy/rustyhand.service /etc/systemd/system/rustyhand.service
# Edit ExecStart path and user as needed
sudo systemctl daemon-reload
sudo systemctl enable --now rustyhand

The service includes security hardening: NoNewPrivileges, ProtectSystem=strict, ProtectHome, PrivateTmp, and resource limits.

Docker

# docker-compose.yml
services:
  rustyhand:
    build: .
    ports:
      - "4200:4200"
    volumes:
      - rustyhand-data:/data
    env_file:
      - path: .env
        required: false
    environment:
      - MINIMAX_API_KEY=${MINIMAX_API_KEY:-}
      - GROQ_API_KEY=${GROQ_API_KEY:-}
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN:-}
    restart: unless-stopped

volumes:
  rustyhand-data:

Cross-compilation

Cross-compilation to aarch64-unknown-linux-gnu is supported via Cross.toml:

cross build --release --target aarch64-unknown-linux-gnu -p rusty-hand-cli

Development

Prerequisites

• Rust 1.75+ (stable) — rust-toolchain.toml auto-selects
• Components: rustfmt, clippy (included in toolchain)

Build & verify

# Compile all crates (use --lib if the daemon binary is locked)
cargo build --workspace --lib

# Run all tests (3,000+)
cargo test --workspace

# Lint — must be 0 warnings
cargo clippy --workspace --all-targets -- -D warnings

# Format check
cargo fmt --all -- --check

Release build

cargo build --release -p rusty-hand-cli
# Binary: target/release/rustyhand (~32 MB)
# LTO + single codegen unit + stripped symbols + opt-level 3

Project structure

rustyhand/
  Cargo.toml                # Workspace manifest (10 member crates)
  Cargo.lock
  rust-toolchain.toml       # Rust stable + rustfmt + clippy
  .env.example              # Environment variable template
  Dockerfile                # Multi-stage build
  docker-compose.yml
  Cross.toml                # Cross-compilation config
  agents/                   # 37 pre-built agent templates (agent.toml each)
  deploy/                   # systemd service, Docker scripts
  scripts/                  # install.sh, install.ps1
  crates/
    rusty-hand-types/       # Core types (config.rs is the master config struct)
    rusty-hand-memory/      # SQLite + vector embeddings (Voyage AI, OpenAI, Ollama)
    rusty-hand-runtime/     # Agent loop + LLM drivers + tools + sandbox
    rusty-hand-wire/        # RHP P2P protocol
    rusty-hand-api/         # Axum HTTP server + routes + dashboard
      src/
        server.rs           # Router setup, middleware, AppState
        routes.rs           # All API endpoint handlers (~7600 LOC)
      static/
        index_body.html     # Dashboard SPA (Alpine.js)
        index_head.html     # CSS + fonts
    rusty-hand-kernel/      # Central kernel (~5300 LOC, 40+ fields)
    rusty-hand-cli/         # CLI + TUI binary
    rusty-hand-channels/    # 37 messaging adapters
    rusty-hand-skills/      # Skill system + ClawHub + OpenClaw compat
    rusty-hand-extensions/  # MCP + vault + OAuth2

Key files for contributors

Common gotchas

• rustyhand.exe may be locked if the daemon is running — use --lib flag or kill daemon first
• New config fields need: struct field + #[serde(default)] + Default impl entry
• New routes must be registered in server.rs router AND implemented in routes.rs
• Dashboard tabs need both HTML in index_body.html and JS data/methods
• AgentLoopResult field is .response not .response_text
• CLI daemon command is start (not daemon)

Benchmarks

All data from official documentation and public repositories — April 2026.

MCP Integration (for AI Agents)

RustyHand exposes itself as an MCP server over stdio, giving any MCP-compatible AI agent (Claude Desktop, Cursor, Windsurf, Claude Code, etc.) full control over the agent OS.

Setup

Add to your MCP client config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "rustyhand": {
      "command": "rustyhand",
      "args": ["mcp"]
    }
  }
}

That's it. The AI agent now has 30+ tools to manage the entire system.

Available MCP Tools

Plus: every running agent automatically becomes an MCP tool named rusty_hand_agent_{name}, so the AI agent can delegate tasks to specialized RustyHand agents.

Example: AI agent workflow via MCP

An AI agent (Claude, GPT, etc.) can autonomously:

1. rustyhand_agent_spawn — create a researcher agent with web access
2. rustyhand_agent_message — ask it to research a topic
3. rustyhand_agent_spawn — create a writer agent
4. rustyhand_agent_message — pass research results to the writer
5. rustyhand_cron_create — schedule the researcher to update weekly
6. rustyhand_budget_status — check how much it all cost

Why an AI agent should use RustyHand

• Delegate work — spawn specialized agents instead of doing everything yourself
• Persistent memory — agents remember context across sessions (vector search + knowledge graph)
• 37 channels — reach users on Telegram, Discord, Slack, etc. without building integrations
• Budget control — set spending limits so agents can't run up costs
• 26 LLM providers — use the best model for each task with automatic fallback
• Autonomous scheduling — cron jobs run agents on schedule, no human needed
• 60 bundled skills — instant expertise in Kubernetes, AWS, PostgreSQL, Git, Python, etc.
• Approval gates — dangerous actions require human approval before executing
• Audit trail — every action is logged in a Merkle hash chain

REST API for Programmatic Access

# Health check
curl http://localhost:4200/api/health

# List agents
curl http://localhost:4200/api/agents

# Spawn an agent
curl -X POST http://localhost:4200/api/agents \
  -H "Content-Type: application/json" \
  -d '{"manifest_toml": "name = \"my-agent\"\nmodule = \"builtin:chat\"\n[model]\nprovider = \"groq\"\nmodel = \"llama-3.3-70b-versatile\"\napi_key_env = \"GROQ_API_KEY\"\nsystem_prompt = \"You are a helpful assistant.\""}'

# Send a message
curl -X POST http://localhost:4200/api/agents/{id}/message \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, what can you do?"}'

# Stream a response (SSE)
curl -X POST http://localhost:4200/api/agents/{id}/message/stream \
  -H "Content-Type: application/json" \
  -d '{"message": "Write a haiku about Rust"}'

# OpenAI-compatible endpoint (drop-in replacement)
curl -X POST http://localhost:4200/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "coder", "messages": [{"role": "user", "content": "Fix this bug"}]}'

# Budget status
curl http://localhost:4200/api/budget

# Memory — store and recall
curl -X PUT http://localhost:4200/api/memory/agents/{id}/kv/project_name \
  -H "Content-Type: application/json" \
  -d '{"value": "rustyhand"}'
curl http://localhost:4200/api/memory/agents/{id}/kv/project_name

SDKs for Python and JavaScript are included in sdk/python/ and sdk/javascript/.

How It Works — Data Flow

User message (CLI / API / Telegram / Discord / ...)
    |
    v
[Channel Adapter] --- converts platform message to unified ChannelMessage
    |
    v
[Kernel Router] --- resolves target agent via bindings/broadcast rules
    |
    v
[Agent Registry] --- looks up AgentManifest + Session
    |
    v
[Agent Loop] (rusty-hand-runtime/src/agent_loop.rs)
    |
    +-- 1. Recall memories (vector similarity via Voyage/OpenAI/Ollama, or text LIKE)
    +-- 2. Build system prompt (SOUL.md + USER.md + TOOLS.md + MEMORY.md + recalled context)
    +-- 3. Call LLM (driver: Anthropic / Gemini / OpenAI-compat)
    |       |-- retry on rate limit (3x, exponential backoff)
    |       |-- fallback to next provider on failure
    |       |-- model routing by complexity (simple/medium/complex)
    +-- 4. If tool_use → execute tool → append result → goto 3 (max 50 iterations)
    |       |-- built-in: file_read, file_write, shell_exec, web_search, web_fetch,
    |       |             memory_store, memory_recall, agent_send, agent_spawn, browser_*
    |       |-- MCP tools: GitHub, Notion, Slack, PostgreSQL, ... (25+ integrations)
    |       |-- skills: 60 prompt-only + Python/WASM/Node.js executable skills
    +-- 5. Extract response text + reply directives
    |
    v
[Metering] --- record token usage + cost, check budget limits
    |
    v
[Session Save] --- persist messages to SQLite, append daily memory log
    |
    v
[Channel Adapter] --- format response for platform, send back
    |
    v
User receives response

Key Types

Extending RustyHand

Add a new LLM provider:

1. Add base URL constant to crates/rusty-hand-types/src/model_catalog.rs
2. Add match arm to crates/rusty-hand-runtime/src/drivers/mod.rs provider_defaults()
3. Most providers use the OpenAI-compatible driver — no new driver code needed

Add a new API endpoint:

1. Add handler function in crates/rusty-hand-api/src/routes.rs
2. Register route in crates/rusty-hand-api/src/server.rs build_router()
3. Add request/response types in crates/rusty-hand-api/src/types.rs if needed

Add a new config field:

1. Add field with #[serde(default)] to struct in crates/rusty-hand-types/src/config.rs
2. Add default value to the Default impl
3. Add to custom Debug impl (redact secrets)

Add a new built-in tool:

1. Add ToolDefinition to builtin_tool_definitions() in crates/rusty-hand-runtime/src/tool_runner.rs
2. Add execution handler in the same file's execute_tool() match

Add a new channel adapter:

1. Create crates/rusty-hand-channels/src/<name>.rs
2. Add pub mod <name> to crates/rusty-hand-channels/src/lib.rs
3. Wire into crates/rusty-hand-api/src/channel_bridge.rs

License

MIT — use it however you want.

Links

• GitHub
• Quick Start
• API Reference
• Python SDK
• JavaScript SDK

Acknowledgments

RustyHand is a fork of OpenFang, originally built by Jaber at RightNow.

Built with Rust. Secured with 16 layers. Agents that actually work for you.