DEV Community

member_e34997ea
member_e34997ea

Posted on • Originally published at ryvos.dev

Getting Started with Ryvos in 5 Minutes

#rust #opensource #ai #tutorial

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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:

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
Enter fullscreen mode Exit fullscreen mode

Then run Ryvos with:

ryvos init -y --provider ollama --model-id qwen2.5:7b
Enter fullscreen mode Exit fullscreen mode

No API key needed. Everything runs on your machine.

Step 3 — Your First Conversation (1 minute)

Start an interactive session:

ryvos
Enter fullscreen mode Exit fullscreen mode

You'll see a prompt. Try something practical:

> Summarize the last 5 git commits in this directory
Enter fullscreen mode Exit fullscreen mode

Ryvos will:

  1. Determine it needs to run git log
  2. Ask for your approval (T3 — shell command) or run automatically depending on your security policy
  3. 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
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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

Step 5 — Check System Health 

ryvos doctor
Enter fullscreen mode Exit fullscreen mode

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:

  1. Parsed your request into a goal with success criteria
  2. Planned which tools to use — in this case, git_log from the 62 built-in tools
  3. Checked the security tier — git log is T1 (low risk), auto-approved
  4. Executed the tool and streamed the output
  5. Evaluated the result against the goal using its built-in Judge
  6. 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
Enter fullscreen mode Exit fullscreen mode

Next Steps

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

Personalize it:

ryvos soul
Enter fullscreen mode Exit fullscreen mode

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

Use the terminal UI:

ryvos tui
Enter fullscreen mode Exit fullscreen mode

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

Run the web UI:

ryvos serve
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

Add MCP servers:

ryvos mcp add filesystem
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)