Ryvos

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 · Cloud · Docs

---

# 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+)

cargo install --path .

Constitutional safety evaluates every action with full audit logging

Get Started

# 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

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

Shell Completions

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 for details.

---

Configuration

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

[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)

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 — Developer-first CLI patterns and ReAct loop design
• Aider — Lightweight coding assistant philosophy
• Aden Hive — Goal-driven graph execution and evolution loops
• OpenClaw — Channel adapter architecture and skills marketplace model
• OpenViking — Hierarchical context database with L0/L1/L2 tiered loading
• Paperclip — Multi-agent fleet orchestration patterns
• Model Context Protocol — Open standard for LLM tool integration

Contributing

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

---

Get Help

• GitHub Issues — bug reports and feature requests
• GitHub 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
• Source: Ryvos/ryvos
• License: MIT
• Homepage: https://ryvos.dev

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