Rustyhand

RustyHand The Agent Operating System

Open-source Agent OS built in Rust. 134K LOC. 10 crates. 1,728 tests. Zero clippy warnings. One binary. Autonomous Telegram agent. Agents that actually work for you.

Quick Start • CLI Reference • API Docs

---

> v0.7.86 — Security & correctness hardening: 84 audit-confirmed fixes across two adversarial sweeps (June 2026) > SSRF redirect re-validation, replay-proof RHP handshake (protocol v2), WASM sandbox isolation, supply-chain install guards, UTF-8 panic fixes, retry/loop-guard correctness, and broad DoS resource caps. Supersedes v0.7.85, adding a cross-platform absolute-path denial fix (Windows) and a quinn-proto advisory bump (RUSTSEC-2026-0185). See the release notes for details. > > Clone → cargo run --release -- start → open the dashboard → talk to an agent. > No API key required. When no provider key is found in the environment, > RustyHand falls back to a deterministic mock driver and seeds four sample > resources so every major dashboard page is interactive on first visit: > > - rusty welcome agent (chat-ready) > - demo-pipeline workflow (2-step sample, click to run) > - sample agent-spawn trigger > - demo-daily-ping cron job (registered, disabled by default) > > A welcome modal on first visit lists all four with one-click navigation. > The CLI startup banner and Docker entrypoint both announce demo mode > as a feature instead of a missing-key warning. Set ANTHROPIC_API_KEY > (or a Kimi / DeepSeek / Zhipu / MiniMax / OpenRouter / Ollama key) and > restart for real LLM responses, or RUSTYHAND_DISABLE_DEMO_MODE=1 to > force a hard fail. > > Highlights since v0.7.41: > - React dashboard — every subsystem is a page: agents, chat, workflows, > automation (cron + triggers), channels, analytics, knowledge graph, skills, > approvals, audit, and a full config.toml editor. > - Autonomous-by-default agents — tuned to act without asking; grant any > agent all 72 tools live via PATCH /api/agents/{id}/config (no respawn). > - 72 built-in tools — shell, web/news search, browser automation, RAG, > knowledge-graph CRUD, file ops, image vision, and config management. > - Trust-by-default security with visible guardrails — GET /api/security > reports the real runtime posture (exec mode, approval policy, per-channel > gating); flip to allowlist/deny with RUSTYHAND_EXEC_MODE. > - Everything persists — audit log (Merkle hash chain), workflows, and > triggers all survive daemon restart and are replayed/validated on boot.

---

Origin

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

Table of Contents

• [What is RustyHand?](#what-is-rustyhand)
• [Installation](#installation)
• [Quick Start](#quick-start)
• [Telegram Setup](#telegram-setup)
• [Configuration](#configuration)
• [CLI Reference](#cli-reference)
• [Autonomous Templates](#autonomous-templates)
• [40 Pre-built Agent Templates](#40-pre-built-agent-templates)
• [Channel Adapters](#channel-adapters)
• [7 LLM Providers](#7-llm-providers)
• [Architecture](#architecture)
• [API Endpoints](#api-endpoints)
• [Dashboard](#dashboard)
• [Security](#security)
• [Deployment](#deployment)
• [Docker Environment Variables](#docker-environment-variables)
• [Development](#development)
• [Benchmarks](#benchmarks)
• [MCP Integration (for AI Agents)](#mcp-integration-for-ai-agents)
• [How It Works — Data Flow](#how-it-works--data-flow)
• [License](#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 directly to your Telegram chat.

Telegram-First Autonomous Agent

Telegram is the primary interface for RustyHand agents. Your agent can:

| Capability | How it works | |------------|-------------| | See photos | Auto-describes images via vision API | | Hear voice | Auto-transcribes voice messages via Whisper | | Receive files | Downloads documents, forwards to agent | | Send files/photos/voice | Sends generated content back to chat | | Ask permission | Inline keyboard buttons (Approve/Reject) pushed automatically | | Show progress | Real-time tool-use updates: "⚙️ web_search..." → "✅ Done" | | Report autonomously | Background tasks push results to your chat without prompting | | 72 built-in tools | Shell, web/news search, browser (wait, JS exec, scroll, download), RAG, knowledge graph, file ops, image vision | | Markdown formatting | Bold, italic, code blocks render natively in Telegram | | Reply threading | Responses reply to the user's message for clean conversation flow | | Sticker/GIF/Location | Agent understands stickers, animations, and shared locations |

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 run directly with env vars (no config.toml needed):

docker run -p 4200:4200 \
  -e ANTHROPIC_API_KEY=your-key \
  -e RUSTYHAND_API_KEY=my-secret-bearer-token \
  -v rustyhand-data:/data \
  ghcr.io/ginkida/rustyhand:latest

All configuration can be set via RUSTYHAND_* environment variables — see [Docker Environment Variables](#docker-environment-variables).

---

Quick Start

Option Zero: Try it in 30 seconds, no API key

The fastest possible first run, no credentials, no configuration:

git clone https://github.com/ginkida/rustyhand
cd rustyhand
cargo run --release -- start
# In another tab: open http://localhost:4200

The dashboard banner will read "DEMO MODE — running on the deterministic mock driver." Spawn an agent, send a message, watch the agent loop run, session grow, audit log fill up. Every reply is [mock] — unmistakably demo, but the full pipeline (sessions, persistence, workflows, cron jobs) is real. Set ANTHROPIC_API_KEY (or any of 26 other supported providers' env vars) and restart for real LLM responses.

Option A: Docker (fastest)

docker run -d --name rustyhand \
  -p 4200:4200 \
  -e ANTHROPIC_API_KEY=your-key \
  -v rustyhand-data:/data \
  ghcr.io/ginkida/rustyhand:latest

# Dashboard: http://localhost:4200
# API:       http://localhost:4200/api/health

To secure the API with a bearer token:

docker run -d --name rustyhand \
  -p 4200:4200 \
  -e ANTHROPIC_API_KEY=your-key \
  -e RUSTYHAND_API_KEY=my-secret-token \
  -v rustyhand-data:/data \
  ghcr.io/ginkida/rustyhand:latest

# Now all API calls require: -H "Authorization: Bearer my-secret-token"

See [Docker Environment Variables](#docker-environment-variables) for all options.

Option B: From binary

# 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. Send a one-shot message
rustyhand message researcher "What are the emerging trends in AI agent frameworks?"

# 6. Launch the interactive TUI dashboard
rustyhand tui

# 7. Run diagnostics
rustyhand doctor

---

Telegram Setup

Telegram is the primary channel for interacting with RustyHand agents. Setup takes 2 minutes:

1. Create a Telegram Bot

1. Message @BotFather on Telegram
2. Send /newbot, follow prompts, get your bot token
3. Set the token: export TELEGRAM_BOT_TOKEN=123456:ABC-DEF...

2. Configure RustyHand

# ~/.rustyhand/config.toml
[channels.telegram]
bot_token_env = "TELEGRAM_BOT_TOKEN"
allowed_users = []    # Empty = allow anyone. Set [123456] for specific user IDs.

3. Start and chat

rustyhand start
# Open Telegram, message your bot
# /agents — list agents
# /agent assistant — select an agent
# Send text, photos, voice messages — the agent handles all of them

What your agent can do in Telegram

You:     [send a voice message]
Agent:   [auto-transcribes via Whisper, processes your request]

You:     [send a photo]
Agent:   [auto-describes the image, responds based on what it sees]

You:     "Search for Rust 2024 edition changes"
Agent:   ⚙️ web_search...
         ✅ web_search
         Here are the key changes in Rust 2024...

Agent:   ⚠️ Agent "coder" wants to execute:
         `shell_exec: rm -rf /tmp/cache`
         [✅ Approve] [❌ Reject]    ⏱️ 60s

You:     [click ✅ Approve]
Agent:   Done! Cache cleared.

Autonomous mode

Agents with schedule_mode = "continuous" or "periodic" run in the background and push results to your Telegram chat automatically — no prompting needed.

# agent.toml
[schedule]
mode = "periodic"
cron = "0 9 * * *"    # Every day at 9 AM

The agent wakes up, performs its task, and sends the result to the last Telegram chat it was used in.

---

Configuration

RustyHand can be configured in two ways:

• Config file (~/.rustyhand/config.toml) — for binary installs
• Environment variables (RUSTYHAND_*) — for Docker, see [Docker Environment Variables](#docker-environment-variables)

API Authentication

When api_key is set, all endpoints (except /api/health) require a Bearer token:

# In config.toml:
api_key = "my-secret-token"

# Or via env var (Docker):
RUSTYHAND_API_KEY=my-secret-token

# Clients must include the header:
curl -H "Authorization: Bearer my-secret-token" http://localhost:4200/api/agents

Without api_key, the API is open (fine for local development).

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 = "anthropic"                 # anthropic, kimi, deepseek, zhipu, minimax, openrouter, ollama
model = "claude-sonnet-4-6"     # Model identifier
api_key_env = "ANTHROPIC_API_KEY"      # Env var holding the API key
# base_url = "https://api.anthropic.com"  # 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 ANY key and RustyHand auto-detects the provider.
# Priority order: Anthropic → Kimi → DeepSeek → Zhipu → MiniMax → OpenRouter.
ANTHROPIC_API_KEY=sk-ant-...       # Claude Opus / Sonnet / Haiku (default)
KIMI_API_KEY=sk-kimi-...            # Kimi Code — Anthropic-compat, 256K ctx
DEEPSEEK_API_KEY=sk-...             # DeepSeek V4 Flash / V4 Pro (V3/R1 legacy, deprecated 2026-07-24)
ZHIPU_API_KEY=...                   # Zhipu GLM-4.6
MINIMAX_API_KEY=eyJ...              # MiniMax M1 / M2.7 (1M context)
OPENROUTER_API_KEY=sk-or-...        # Universal gateway (GPT/Gemini/Grok/etc.)

# Local LLM — no key needed, just run `ollama serve`
# (Base URL defaults to http://localhost:11434/v1 — override only if needed)

# Embedding-only upstreams (independent of LLM provider)
VOYAGE_API_KEY=pa-...                # Voyage AI (voyage-3-lite, code, legal, ...)
# OPENAI_API_KEY can also be used for text-embedding-3-* — not for LLM completion.

# 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 kimi   # Switch provider
rustyhand config set-key kimi                      # Interactively save API key
rustyhand config test-key kimi                     # 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 tools [--json] | List all 72 built-in tools, grouped by category (offline) | | rustyhand tui | Launch interactive TUI dashboard | | rustyhand dashboard | Open web dashboard in browser | | rustyhand chat [agent] | Quick chat with an agent | | rustyhand message | 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 templates [--json] | List the bundled agent templates (offline) | | rustyhand agent spawn | Spawn from a manifest file | | rustyhand agent list [--json] | List running agents | | rustyhand agent chat | Interactive chat with an agent by ID | | rustyhand agent kill | 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 | Send a test message | | rustyhand channel enable | Enable a channel | | rustyhand channel disable | Disable a channel |

Models

| Command | Description | |---------|-------------| | rustyhand models list [--provider X]

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ginkida
• Source: ginkida/rustyhand
• License: MIT

Install and usage instructions live in the source repository linked above.