# Ryvos

> Open-source autonomous AI assistant with 5-tier security, 62 tools, 14 LLM providers. Written in Rust. Single binary.

- **Type:** MCP server
- **Install:** `agentstack add mcp-ryvos-ryvos`
- **Verified:** Pending review
- **Seller:** [Ryvos](https://agentstack.voostack.com/s/ryvos)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Ryvos](https://github.com/Ryvos)
- **Source:** https://github.com/Ryvos/ryvos
- **Website:** https://ryvos.dev

## Install

```sh
agentstack add mcp-ryvos-ryvos
```

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

## About

# Ryvos

### Open-source AI agent runtime built in Rust. Self-hosted. 15–30 MB RAM. 18+ LLM providers.

[](https://github.com/Ryvos/ryvos/stargazers)
[](LICENSE)
[](https://www.rust-lang.org)
[](https://github.com/Ryvos/ryvos/releases)
[](https://github.com/Ryvos/ryvos/actions)
[](#quick-start)

**Goal-Driven Agents · 18+ LLM Providers · 86+ Tools · DAG Workflows · MCP-Native · Constitutional AI Safety · Single Binary**

[Quick Start](#quick-start) · [Why Ryvos](#why-ryvos) · [Features](#features) · [Architecture](#architecture) · [Security](#security) · [Roadmap](#roadmap)

[Website](https://ryvos.dev) · [Cloud](https://cloud.ryvos.dev) · [Docs](https://ryvos.dev/docs)

---

```bash
# One-line install (Linux / macOS)
curl -fsSL https://raw.githubusercontent.com/Ryvos/ryvos/main/install.sh | sh
ryvos init    # pick your LLM provider, paste an API key
ryvos         # start your AI coding assistant
```

---

## Why Ryvos?

Most AI coding assistants are built on TypeScript or Python runtimes that were never designed for autonomous, always-on operation. They're heavy, insecure, and fragile to deploy.

Ryvos is a complete reimagination — built in Rust from scratch as a true **autonomous AI agent runtime**:

| | Typical AI assistants | **Ryvos** |
|---|---|---|
| **Language** | TypeScript / Python | **Rust** |
| **Memory (idle)** | 200–500 MB | **15–30 MB** |
| **Execution model** | Run until max_turns | **Goal-driven with Judge verdict** |
| **Tool security** | None (arbitrary code) | **Constitutional AI safety + Docker sandboxing** |
| **Dangerous command detection** | None | **9 built-in patterns (rm -rf, DROP TABLE, curl\|bash…)** |
| **Deployment** | npm/pip + runtime + Docker | **Single static binary** |
| **MCP support** | Plugin/community | **Native (stdio + SSE/Streamable HTTP)** |
| **Parallel tool execution** | Rare | **Built-in** |
| **Multi-agent workflows** | Separate orchestration layer | **Built-in DAG engine + orchestrator** |
| **Channel adapters** | Separate projects | **Built-in (Telegram, Discord, Slack, WhatsApp)** |
| **HTTP Gateway** | Separate project | **Built-in with Web UI + RBAC** |

If you've used Claude Code, Aider, or Cursor and wanted something lighter, self-hosted, or with a proper security model — Ryvos is built for you.

---

## What is Ryvos?

Ryvos is an open-source, autonomous AI coding assistant and agent runtime you run on your own hardware. It connects to **18+ LLM providers** (Anthropic, OpenAI, Gemini, Azure, Cohere, Ollama, Groq, OpenRouter, Together, Fireworks, Cerebras, xAI, Mistral, Perplexity, DeepSeek, Bedrock, Claude Code, GitHub Copilot), executes tasks through **86+ sandboxed tools**, and reaches you on the channels you already use — Telegram, Discord, Slack, WhatsApp, Webhooks — plus a built-in Web UI and terminal interface.

Written in **Rust**. Ships as a **single binary**. Uses **15–30 MB of RAM**.

---

## Performance

Benchmarks from a live v0.8.2 instance on Linux x86_64 (Intel i3-10105, 12 GB RAM).

| Metric | Value |
|--------|-------|
| Binary size | 45 MB (stripped, thin LTO) |
| CLI startup | 
Build from source (Rust 1.75+)

```bash
cargo install --path .
```

*Constitutional safety evaluates every action with full audit logging*

### Get Started

```bash
# Interactive setup — pick a provider, configure security, install service
ryvos init

# Non-interactive setup (defaults to Ollama / qwen2.5:7b for local inference)
ryvos init -y --provider ollama --model-id qwen2.5:7b

# Start your AI coding assistant
ryvos

# Ask a quick question and exit
ryvos run "Summarize the last 5 git commits in this repo"

# Launch the terminal UI
ryvos tui

# Start the Web UI + HTTP/WebSocket gateway
ryvos serve

# Always-on: Telegram + Discord + Slack + WhatsApp + gateway in one process
ryvos daemon --gateway

# Check system health
ryvos doctor
```

### Uninstall

```bash
rm ~/.local/bin/ryvos
rm -rf ~/.ryvos   # optional: remove config and data
```

### Shell Completions

```bash
ryvos completions bash > ~/.local/share/bash-completion/completions/ryvos  # bash
ryvos completions zsh > ~/.zfunc/_ryvos                                    # zsh
ryvos completions fish > ~/.config/fish/completions/ryvos.fish             # fish
```

### Commands

| Command | Description |
|---------|-------------|
| `ryvos` | Interactive conversation (default) |
| `ryvos run ` | Ask a question, get an answer, exit |
| `ryvos tui` | Terminal UI with streaming output |
| `ryvos serve` | Web UI + HTTP/WebSocket gateway |
| `ryvos daemon` | Always-on assistant (Telegram, Discord, Slack, WhatsApp) |
| `ryvos daemon --gateway` | Always-on + Web UI in one process |
| `ryvos init` | Interactive setup wizard |
| `ryvos init -y` | Non-interactive setup with defaults |
| `ryvos soul` | Personalize your agent (5-question interview → SOUL.md) |
| `ryvos config` | Print resolved configuration |
| `ryvos doctor` | System health checks (API, workspace, DB, channels, cron, MCP, security) |
| `ryvos health` | Tool health statistics |
| `ryvos mcp list` | List configured MCP servers |
| `ryvos mcp add ` | Add an MCP server |
| `ryvos completions ` | Generate shell completions (bash, zsh, fish) |

---

## Architecture

Ryvos is a Cargo workspace with 10 crates. Together they form a complete autonomous AI agent runtime — goal-driven LLM reasoning, DAG workflow orchestration, tool execution, security enforcement, persistent memory, multi-channel inbox, and observability — all in one binary.

```
┌─────────────────────────────────────────────────────┐
│                     ryvos (CLI)                     │
├──────────┬──────────┬───────────┬───────────────────┤
│ ryvos-tui│  ryvos-  │  ryvos-   │  ryvos-channels   │
│  (TUI)   │ gateway  │  agent    │(Telegram/Discord/  │
│          │(HTTP/WS) │           │ Slack/WhatsApp)    │
├──────────┴──────────┤           ├───────────────────┤
│    ryvos-skills     │           │    ryvos-mcp      │
│  (Lua/Rhai loader)  │           │  (MCP client)     │
├─────────────────────┼───────────┼───────────────────┤
│    ryvos-tools      │ ryvos-llm │  ryvos-memory     │
│  (tool registry)    │(streaming │  (SQLite store)   │
│                     │  client)  │                   │
├─────────────────────┴───────────┴───────────────────┤
│                   ryvos-core                        │
│    (config, error types, event bus, security,       │
│     goal system, traits, types)                     │
└─────────────────────────────────────────────────────┘
```

| Crate | Purpose |
|-------|---------|
| `ryvos-core` | Config, error types, scoped event bus, security policy, goal system, traits |
| `ryvos-llm` | LLM client abstraction with streaming support (18+ providers) |
| `ryvos-tools` | Tool registry, 86+ built-in tools across 18 categories |
| `ryvos-agent` | ReAct loop, SecurityGate, ApprovalBroker, Guardian watchdog, Judge, GoalEvaluator, OutputValidator, CheckpointStore, RunLogger, CronScheduler, GraphExecutor, MultiAgentOrchestrator |
| `ryvos-memory` | SQLite-backed session and history storage |
| `ryvos-gateway` | Axum HTTP/WS server, Web UI, role-based auth middleware |
| `ryvos-channels` | Telegram, Discord, Slack, WhatsApp adapters with DM policy enforcement |
| `ryvos-mcp` | MCP client (stdio + SSE transports) with sampling control |
| `ryvos-skills` | Drop-in skill loader (Lua/Rhai) with manifest validation |
| `ryvos-tui` | Terminal UI built on ratatui with adaptive banner |

---

## Security

Ryvos uses a **constitutional self-learning safety model** — the agent reasons about the appropriateness of every action using 7 built-in principles.

**No tool is ever blocked.** Safety comes from understanding, not prohibition.

### How It Works

1. **Tool classification** — every tool has a security tier (T0 safe → T4 critical) for audit and context
2. **Constitutional reasoning** — the agent evaluates each action against 7 principles: Preservation, Intent Match, Proportionality, Transparency, Boundaries, Secrets, Learning
3. **Safety Memory** — the agent learns from past mistakes. SafetyMemory stores lessons as corrective rules that improve behavior over time
4. **Full audit trail** — every tool call is logged with input, output, safety reasoning, and outcome

### Additional Safety Layers

- **Dangerous pattern detection** — 9 built-in patterns (rm -rf, DROP TABLE, curl|bash, etc.) trigger explicit constitutional reasoning
- **Docker sandboxing** — optional isolated execution for file system and network operations
- **Optional checkpoints** — configure `pause_before` for tools that should wait for human acknowledgment
- **Budget enforcement** — monthly dollar limits with soft warnings and hard stops

> The old tier-based blocking system has been replaced. Tiers are retained for classification and backward compatibility, but they do not gate execution. See the [security documentation](https://ryvos.dev/docs/security/overview) for details.

---

## Configuration

Configuration lives in `~/.ryvos/config.toml` (created by `ryvos init`). You can also place a `ryvos.toml` in the current directory.

```toml
[agent]
max_turns = 25
parallel_tools = true
enable_self_eval = true

[agent.checkpoint]
enabled = true

[agent.log]
enabled = true
log_dir = "~/.ryvos/logs"

[agent.guardian]
stall_timeout_secs = 60
doom_loop_threshold = 5
budget_tokens = 100000

[model]
provider = "anthropic"
model_id = "claude-sonnet-4-20250514"
api_key = "${ANTHROPIC_API_KEY}"

# Local / self-hosted (no API key required):
# provider = "ollama"
# model_id = "qwen2.5:7b"

[security]
mode = "constitutional"       # constitutional | legacy-tier
pause_before = ["shell_exec"] # optional human checkpoints
budget_monthly_usd = 50.0
budget_warn_pct = 80

[gateway]
bind = "127.0.0.1:18789"

[[gateway.api_keys]]
name = "web-ui"
key = "rk_..."
role = "operator"    # viewer | operator | admin

[channels.telegram]
bot_token = "${TELEGRAM_BOT_TOKEN}"
dm_policy = "allowlist"
allowed_users = [123456789]

[mcp.servers.filesystem]
transport = { type = "stdio", command = "npx", args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] }
```

---

## Roadmap

### Completed
- [x] Goal-driven execution with weighted success criteria
- [x] Two-level Judge system (deterministic + LLM)
- [x] Decision tracking and failure journal
- [x] Structured output validation and repair
- [x] JSONL runtime logging (L1/L2/L3)
- [x] Phase-aware context compaction
- [x] Three-layer prompt composition
- [x] Checkpoint / resume
- [x] DAG workflow engine (graph execution)
- [x] Multi-agent orchestrator with capability-based routing
- [x] Scoped EventBus with filtered subscriptions
- [x] Cron scheduler with persistent resume
- [x] Guardian watchdog (stall, doom loop, budget detection)
- [x] Multi-channel inbox (Telegram, Discord, Slack)
- [x] HTTP/WebSocket gateway with Web UI
- [x] Heartbeat system with smart suppression and alert routing
- [x] WhatsApp channel adapter (shipped in v0.5.0)
- [x] Browser control — navigate, click, extract, screenshot (shipped in v0.5.0)
- [x] Ryvos Cloud — hosted assistant with managed sessions (in preview at [cloud.ryvos.dev](https://cloud.ryvos.dev))

### Upcoming
- [ ] Pre-built binaries (Windows, macOS, Linux) via GitHub Releases
- [ ] `cargo install ryvos` from crates.io
- [ ] Signal, iMessage, and Google Chat channel adapters
- [ ] Voice mode — wake word detection + speech-to-text + TTS
- [ ] Mobile companion apps (iOS, Android) via WebSocket
- [ ] Live Canvas — real-time document/artifact editing in Web UI
- [ ] SOC 2 compliance documentation
- [ ] Signed & verified skill marketplace
- [ ] MCP sampling support (server-initiated LLM calls)

---

## Acknowledgments & Inspirations

Ryvos stands on the shoulders of great projects:

- [Claude Code](https://claude.ai/code) — Developer-first CLI patterns and ReAct loop design
- [Aider](https://github.com/paul-gauthier/aider) — Lightweight coding assistant philosophy
- [Aden Hive](https://github.com/aden-hive/hive) — Goal-driven graph execution and evolution loops
- [OpenClaw](https://github.com/openclaw/openclaw) — Channel adapter architecture and skills marketplace model
- [OpenViking](https://github.com/volcengine/OpenViking) — Hierarchical context database with L0/L1/L2 tiered loading
- [Paperclip](https://github.com/paperclipai/paperclip) — Multi-agent fleet orchestration patterns
- [Model Context Protocol](https://modelcontextprotocol.io) — Open standard for LLM tool integration

## Contributing

We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

---

## Get Help

- [GitHub Issues](https://github.com/Ryvos/ryvos/issues) — bug reports and feature requests
- [GitHub Discussions](https://github.com/Ryvos/ryvos/discussions) — questions and community

---

## License

[MIT](LICENSE)

## Source & license

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

- **Author:** [Ryvos](https://github.com/Ryvos)
- **Source:** [Ryvos/ryvos](https://github.com/Ryvos/ryvos)
- **License:** MIT
- **Homepage:** https://ryvos.dev

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:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **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-ryvos-ryvos
- Seller: https://agentstack.voostack.com/s/ryvos
- 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%.