# Rustyhand

> Agent OS in Rust — one binary, 37 agents, 26 LLM providers, 37 channels (Telegram/Discord/Slack...), MCP server, A2A protocol, 120+ API endpoints, web dashboard

- **Type:** MCP server
- **Install:** `agentstack add mcp-ginkida-rustyhand`
- **Verified:** Pending review
- **Seller:** [ginkida](https://agentstack.voostack.com/s/ginkida)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ginkida](https://github.com/ginkida)
- **Source:** https://github.com/ginkida/rustyhand

## Install

```sh
agentstack add mcp-ginkida-rustyhand
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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](https://github.com/RightNow-AI/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)

```bash
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)

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

### From source

```bash
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

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

Or run directly with env vars (no config.toml needed):

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

```bash
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)

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

```bash
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

```bash
# 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](https://t.me/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

```toml
# ~/.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

```bash
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.

```toml
# 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:

```bash
# 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`

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

```bash
# 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

```bash
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](https://github.com/ginkida)
- **Source:** [ginkida/rustyhand](https://github.com/ginkida/rustyhand)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** yes
- **Shell / process execution:** yes
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-ginkida-rustyhand
- Seller: https://agentstack.voostack.com/s/ginkida
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.