Getting Started with Ryvos in 5 Minutes

member_e34997ea — Sat, 14 Mar 2026 10:04:33 +0000

Getting Started with Ryvos in 5 Minutes

Ryvos is an open-source AI coding assistant and agent runtime built in Rust. One binary, 15–30 MB RAM, 14 LLM providers — runs on your own hardware.

You can have a fully functional AI coding assistant running locally in the time it takes to make coffee. Here's exactly how.

Prerequisites

Linux or macOS (Windows support coming — see roadmap)
An LLM API key — OR a local Ollama instance (free, no account needed)
curl and sh (pre-installed on every *nix system)

Step 1 — Install (30 seconds)

curl -fsSL https://raw.githubusercontent.com/Ryvos/ryvos/main/install.sh | sh

That's it. The installer:

Downloads the correct binary for your OS and architecture
Places it in ~/.local/bin/ryvos (added to your PATH automatically)
Creates ~/.ryvos/ for config and data

Verify it worked:

ryvos --version
# ryvos 0.5.0

No Rust required. The install script downloads a pre-built binary. You don't need a Rust toolchain unless you want to build from source.

Step 2 — Connect an LLM Provider (2 minutes)

Run the interactive setup wizard:

ryvos init

You'll be asked to choose a provider and paste an API key. Ryvos supports 14 providers — here are the most common starting points:

Option A: Anthropic Claude (recommended for best results)

When prompted:

Provider: anthropic
Model: claude-sonnet-4-20250514
API key: your key from console.anthropic.com

Option B: OpenAI

Provider: openai
Model: gpt-4o
API key: your key from platform.openai.com

Option C: Ollama (free, fully local, no account)

First install Ollama and pull a model:

ollama pull qwen2.5:7b

Then run Ryvos with:

ryvos init -y --provider ollama --model-id qwen2.5:7b

No API key needed. Everything runs on your machine.

Step 3 — Your First Conversation (1 minute)

Start an interactive session:

ryvos

You'll see a prompt. Try something practical:

> Summarize the last 5 git commits in this directory

Ryvos will:

Determine it needs to run git log
Ask for your approval (T3 — shell command) or run automatically depending on your security policy
Execute the command, read the output, and give you a plain-English summary

Try a few more:

> What files did I change today?
> Explain what this function does
> Write a unit test for the auth module

Step 4 — Run a Quick One-Off Task

Don't want interactive mode? Use ryvos run:

ryvos run "List all TODO comments in the current directory and group them by file"

This runs the agent, completes the task, and exits. Good for scripts and aliases.

Step 5 — Check System Health

ryvos doctor

This runs diagnostics on your setup: API connectivity, workspace access, database, security policy, MCP servers if configured. Fix any warnings before going further.

What Just Happened?

When you ran that first task, Ryvos:

Parsed your request into a goal with success criteria
Planned which tools to use — in this case, git_log from the 62 built-in tools
Checked the security tier — git log is T1 (low risk), auto-approved
Executed the tool and streamed the output
Evaluated the result against the goal using its built-in Judge
Returned the answer — and stopped. No infinite loops.

This is goal-driven execution. The agent runs until the task is done, not until it hits a turn limit.

Security: What Can and Can't It Do?

By default, Ryvos uses a conservative security policy:

Tool tier	Example	Default behavior
T0 — Safe	Read a file	Runs automatically
T1 — Low	Web search, git log	Runs automatically
T2 — Medium	Write a file	Asks for approval
T3 — High	Run a shell command	Asks for approval
T4 — Critical	`rm -rf`, `DROP TABLE`	Blocked outright

You can adjust this in ~/.ryvos/config.toml:

[security]
auto_approve_up_to = "t2"    # auto-approve file writes too
deny_above = "t4"            # block destructive commands
approval_timeout_secs = 60

Next Steps

You've got a working AI coding assistant. Here's where to go from here:

Personalize it:

ryvos soul

A 5-question interview that shapes the agent's personality, tone, and how proactively it asks for clarification.

Use the terminal UI:

ryvos tui

A full ratatui-based TUI with streaming output — cleaner than the REPL for longer sessions.

Run the web UI:

ryvos serve

Opens a browser-accessible interface at http://localhost:18789. Useful when you want to share access or use it from another machine.

Connect to Telegram / Discord / Slack:
Add channel config to ~/.ryvos/config.toml and run:

ryvos daemon --gateway

Your assistant is now always on — message it from your phone.

Add MCP servers:

ryvos mcp add filesystem

Model Context Protocol lets you connect Ryvos to external tools and data sources — filesystem, databases, APIs, browser automation.

Troubleshooting

ryvos: command not found
The installer adds ~/.local/bin to your PATH, but your current shell session may not have refreshed. Run:

source ~/.bashrc   # or ~/.zshrc

API key errors
Run ryvos doctor — it will test connectivity to your configured provider and show the exact error.

Permission denied on tool use
Check your security policy with ryvos config. Your auto_approve_up_to tier may be too restrictive for the task you're running.

Resources

Ryvos is open source (MIT). If this tutorial helped, a GitHub star is appreciated — it helps other developers find the project.

DEV Community: member_e34997ea

Getting Started with Ryvos in 5 Minutes

Getting Started with Ryvos in 5 Minutes

Prerequisites

Step 1 — Install (30 seconds)

Step 2 — Connect an LLM Provider (2 minutes)

Option A: Anthropic Claude (recommended for best results)

Option B: OpenAI

Option C: Ollama (free, fully local, no account)

Step 3 — Your First Conversation (1 minute)

Step 4 — Run a Quick One-Off Task

Step 5 — Check System Health

What Just Happened?

Security: What Can and Can't It Do?

Next Steps

Troubleshooting

Resources