Rustyhand

<p align="center"> <img src="crates/rusty-hand-api/static/logo.png" width="500" alt="RustyHand Logo" /> </p> <h1 align="center">RustyHand</h1> <h3 align="center">The Agent Operating System</h3> <p align="center"> Open-source Agent OS built in Rust. 134K LOC. 10 crates. 3,000+ tests. Zero clippy warnings.<br/> <strong>One binary. Battle-tested. Agents that actually work for you.</strong> </p> <p align="center"> <a href="https://github.com/ginkida/rustyhand#quick-start">Quick Start</a> &bull; <a href="https://github.com/ginkida/rustyhand#cli-reference">CLI Reference</a> &bull; <a href="https://github.com/ginkida/rustyhand#api-endpoints">API Docs</a> </p> <p align="center"> <img src="https://img.shields.io/badge/language-Rust-orange?style=flat-square" alt="Rust" /> <img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT" /> <img src="https://img.shields.io/badge/version-0.1.0-green?style=flat-square" alt="v0.1.0" /> <img src="https://img.shields.io/badge/tests-3,000%2B%20passing-brightgreen?style=flat-square" alt="Tests" /> <img src="https://img.shields.io/badge/clippy-0%20warnings-brightgreen?style=flat-square" alt="Clippy" /> </p>

---

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

| Command | Description | |---------|-------------| | rustyhand init | Initialize ~/.rustyhand/ and default config | | rustyhand start | Start the daemon (API server + kernel) | | rustyhand stop | Stop the running daemon | | rustyhand status [--json] | Show kernel status | | rustyhand health [--json] | Quick daemon health check | | rustyhand doctor [--repair] | Run diagnostic checks | | rustyhand tui | Launch interactive TUI dashboard | | rustyhand dashboard | Open web dashboard in browser | | rustyhand chat [agent] | Quick chat with an agent | | rustyhand message <agent> <text> | Send a one-shot message | | rustyhand logs [--follow] [--lines N] | Tail the log file | | rustyhand reset [--confirm] | Reset local config and state |

Agents

| Command | Description | |---------|-------------| | rustyhand agent new [template] | Spawn from a template (interactive picker if omitted) | | rustyhand agent spawn <manifest.toml> | Spawn from a manifest file | | rustyhand agent list [--json] | List running agents | | rustyhand agent chat <id> | Interactive chat with an agent by ID | | rustyhand agent kill <id> | Kill an agent |

Channels

| Command | Description | |---------|-------------| | rustyhand channel list | List configured channels and status | | rustyhand channel setup [name] | Interactive channel setup wizard | | rustyhand channel test <name> | Send a test message | | rustyhand channel enable <name> | Enable a channel | | rustyhand channel disable <name> | Disable a channel |

Models

| Command | Description | |---------|-------------| | rustyhand models list [--provider X] | Browse available models | | rustyhand models aliases | Show model shorthand names | | rustyhand models providers | List providers and their auth status | | rustyhand models set [model] | Set the default model |

Skills

| Command | Description | |---------|-------------| | rustyhand skill install <source> | Install from ClawHub, local path, or git URL | | rustyhand skill list | List installed skills | | rustyhand skill search <query> | Search ClawHub marketplace | | rustyhand skill remove <name> | Remove a skill | | rustyhand skill create | Scaffold a new skill |

Workflows & scheduling

| Command | Description | |---------|-------------| | rustyhand workflow list | List workflows | | rustyhand workflow create <file.json> | Cre