riva 0.2.0

AI Agent Task Manager - discover and monitor AI coding agents running on your machine

🧐 rivA

Observe, monitor, and control local AI agents running on your machine.

Riva is a local-first observability and control plane for AI agents. It helps you understand what agents are running on your machine, what they are doing, and how they are behaving in real time.

As agent frameworks push toward autonomy, visibility often disappears. Riva exists to restore clarity, safety, and trust.

Getting Started · How it works · CLI Reference · Web Dashboard · Security · Contributing

---

Demo

Agent Overview	Resource Monitoring
coming soon	coming soon

---

How it works

Local Agents (Claude Code / Codex CLI / Gemini CLI / LangGraph / CrewAI / AutoGen / ...)
                 |
                 v
        +------------------+
        |       Riva       |    discovery, metrics, logs, lifecycle
        |  (observability) |
        +--------+---------+
                 |
        +--------+---------+
        |        |         |
      CLI      TUI    Web Dashboard

Riva runs entirely on your machine. It observes agent behavior but does not execute agent actions.

---

Highlights

• Agent discovery — detect locally running agents across 13 frameworks and growing
• Lifecycle visibility — see when agents start, stop, crash, or hang
• Resource tracking — CPU, memory, and uptime per agent in real time
• Token usage stats — track token consumption, model usage, and tool call frequency
• Environment scanning — detect exposed API keys in environment variables
• Security audit — riva audit checks for config permission issues, exposed secrets, and dashboard misconfiguration
• Web dashboard — Flask-based dashboard with REST API, security headers, and optional auth token
• Framework-agnostic — works across multiple agent frameworks and custom agents
• Local-first — no cloud, no telemetry, no hidden data flows

---

Supported Frameworks

Riva ships with built-in detectors for these agent frameworks:

Framework	Binary / Process	Config Dir	API Domain
Claude Code	claude	~/.claude	api.anthropic.com
Codex CLI	codex	~/.codex	api.openai.com
Gemini CLI	gemini	~/.gemini	generativelanguage.googleapis.com
OpenClaw	openclaw, clawdbot	~/.openclaw	varies
LangGraph	langgraph / Python	~/.langgraph	api.smith.langchain.com
CrewAI	crewai / Python	~/.crewai	app.crewai.com
AutoGen	autogen / Python	~/.autogen	varies
OpenCode	opencode	~/.config/opencode	varies

Python-based frameworks (LangGraph, CrewAI, AutoGen) are detected by matching python processes whose command line references the framework.

Adding more frameworks — Riva is extensible via:

1. Built-in detectors in src/riva/agents/
2. Third-party pip packages using [project.entry-points."riva.agents"]
3. Plugin scripts dropped into ~/.config/riva/plugins/

---

What Riva Is Not

Riva is intentionally not:

• An AI agent
• An orchestration framework
• A cloud monitoring service
• A replacement for agent runtimes

Riva does not make decisions. It makes agent behavior visible.

---

Requirements

• macOS (Ventura, Sonoma, Sequoia) or Linux
• Windows via WSL2
• Python 3.11+

---

Quick Start

Install from PyPI

pip install riva-agent

Install via bash script

curl -fsSL https://raw.githubusercontent.com/sarkar-ai/riva/main/install.sh | bash

Install from source

git clone https://github.com/sarkar-ai/riva.git
cd riva
pip install -e ".[test]"

Verify

riva --help

---

CLI Reference

riva scan

One-shot scan for running AI agents.

riva scan              # Rich table output
riva scan --json       # JSON output

riva watch

Launch the live TUI dashboard with real-time resource monitoring.

riva watch

riva stats

Show token usage and tool execution statistics.

riva stats                        # All agents
riva stats --agent "Claude"       # Filter by name
riva stats --json                 # JSON output

riva list

Show all known agent types and their install status.

riva list

riva config

Show parsed configurations for detected agents.

riva config

riva audit

Run a security audit and print a report.

riva audit             # Rich table with PASS/WARN/FAIL
riva audit --json      # JSON output

Checks performed:

• API key / secret exposure in environment variables
• Config directory and file permissions (group/other-accessible)
• Web dashboard bind address and status
• Plugin directory existence and permissions
• MCP server configs — HTTP endpoints, shell commands, temp-dir references
• Plaintext token scanning across all agent config files
• Agent processes running as root (UID 0)
• Agent binary writability (group/world-writable binaries)
• Suspicious launcher detection (unknown or script-interpreter parents)
• Orphan process detection
• Network checks (with --network): unencrypted connections, unknown destinations, excessive connections, stale sessions

See Security Audit Details for the full list and rationale.

---

Web Dashboard

Start / Stop

riva web start                  # Background daemon
riva web start -f               # Foreground
riva web start --auth-token MY_SECRET   # With API auth
riva web stop                   # Stop daemon
riva web status                 # Check status
riva web logs                   # View logs
riva web logs -f                # Follow logs

Custom host and port

riva web --host 0.0.0.0 --port 9090 start

A warning is printed when binding to a non-localhost address.

API endpoints

Endpoint	Description
GET /	HTML dashboard
GET /api/agents	Running agents (fast poll)
GET /api/agents/history	CPU/memory history
GET /api/stats	Token usage stats (cached 30s)
GET /api/env	Environment variables
GET /api/registry	Known agent types
GET /api/config	Agent configurations

Authentication

When started with --auth-token, all /api/* routes require a Authorization: Bearer <token> header. The index page (/) remains accessible without authentication.

# Start with auth
riva web start --auth-token secret123

# Access API
curl -H "Authorization: Bearer secret123" http://127.0.0.1:8585/api/agents

Security headers

All responses include:

• X-Content-Type-Options: nosniff
• X-Frame-Options: DENY
• Content-Security-Policy: default-src 'self' 'unsafe-inline'
• X-XSS-Protection: 1; mode=block
• Referrer-Policy: strict-origin-when-cross-origin

---

Security

• Runs locally — no network exposure by default
• Web dashboard binds to 127.0.0.1 by default
• Non-localhost binding triggers a visible warning
• Optional bearer token auth for the web API
• Security headers on all HTTP responses
• riva audit performs 15+ automated security checks (see below)
• No agent execution privileges — read-only observation

See SECURITY.md for the full security policy.

Security Audit Details

riva audit runs a comprehensive set of checks designed to catch real-world threats to local AI agent deployments. Each check below links to supporting evidence for why it matters.

Credential & Token Exposure

Check	What it does	Why it matters
API Key Exposure	Scans environment variables for keys, tokens, and secrets	GitHub found 39M+ leaked secrets in 2024 alone
Plaintext Token Scan	Scans agent config files for 14 token patterns (sk-, ghp_, AKIA, AIza, sk-ant-, eyJ, hf_, gsk_, etc.)	API keys stored in plaintext config files are a top credential exposure vector (OWASP A07:2021)

Covered config files per agent: settings.json, config.json, mcp.json, .env, config.toml (Codex CLI), config.ts (Continue.dev), OAI_CONFIG_LIST (AutoGen), langgraph.json (LangGraph), mcp_config.json (Windsurf). Also scans VS Code extension directories (Cline, Copilot, Continue) and macOS Application Support paths.

Permissions

Check	What it does	Why it matters
Config Directory Permissions	Flags config dirs readable by group/other	Other local users or malware can read API keys and session data
Config File Permissions	Checks individual config files for mode & 0o077	Per-file permission hardening — a directory can be safe while files inside are over-permissioned
Binary Permissions	Flags agent binaries that are group/world-writable	A writable binary can be replaced with a trojan — classic binary planting
Plugin Directory	Flags existence and permissions of ~/.config/riva/plugins/	Plugin directories are arbitrary code execution surfaces

Process Safety

Check	What it does	Why it matters
Running as Root	Flags agent processes with UID 0	AI agents should follow principle of least privilege — root agents can access any file or process
Suspicious Launcher	Flags unknown launch types or script-interpreter parents (python, node)	Unexpected parent processes may indicate process injection or unauthorized agent execution
Orphan Processes	Detects agent child processes whose parent has died	Orphaned agent processes continue consuming resources and may hold open API connections

MCP (Model Context Protocol) Supply Chain

Check	What it does	Why it matters
MCP HTTP Endpoints	Flags MCP servers using http:// instead of https://	Unencrypted MCP connections expose tool calls and responses to network sniffing (Invariant Labs MCP security research)
MCP Shell Commands	Flags MCP servers whose stdio command is bash, sh, cmd, etc.	Shell-based MCP servers enable arbitrary command execution via prompt injection
MCP Temp Dir References	Flags MCP server commands or args referencing /tmp/	Temp directories are world-writable — MCP binaries there can be swapped by any local user

Scans 6 well-known MCP config paths plus dynamically discovered mcp.json/mcp_config.json in every installed agent's config directory.

Network (with --network flag)

Check	What it does	Why it matters
Unencrypted Connections	Flags connections to known API domains on non-443 ports	API traffic should always be TLS-encrypted
Unknown Destinations	Flags ESTABLISHED connections to unrecognized hosts	May indicate data exfiltration or unauthorized API calls
Excessive Connections	Flags agents with >50 active connections	Possible connection leak or C2 beaconing
Stale Sessions	Flags CLOSE_WAIT/TIME_WAIT connections	Connection cleanup failures waste resources and may indicate issues

Dashboard

Check	What it does	Why it matters
Dashboard Status	Warns when the web dashboard is running	A running dashboard is an attack surface — verify it's not exposed to the network

---

Architecture

src/riva/
├── agents/              # Agent detection and parsing
│   ├── base.py          # AgentInstance, AgentStatus, BaseDetector
│   ├── registry.py      # Agent registry
│   ├── claude_code.py   # Claude Code detector
│   ├── codex_cli.py     # Codex CLI detector
│   ├── gemini_cli.py    # Gemini CLI detector
│   ├── openclaw.py      # OpenClaw detector
│   ├── langgraph.py     # LangGraph / LangChain detector
│   ├── crewai.py        # CrewAI detector
│   └── autogen.py       # AutoGen detector
├── core/                # Core logic
│   ├── audit.py         # Security audit checks
│   ├── env_scanner.py   # Environment variable scanning
│   ├── monitor.py       # Resource monitoring (CPU, memory)
│   ├── scanner.py       # Process scanning
│   └── usage_stats.py   # Token/tool usage parsing
├── tui/                 # Terminal UI (Rich)
│   ├── components.py    # Rich table builders
│   └── dashboard.py     # Live dashboard
├── web/                 # Flask web dashboard
│   ├── server.py        # Flask app, REST API, security middleware
│   └── daemon.py        # Background daemon management
├── utils/               # Shared utilities
│   ├── formatting.py    # Display formatting helpers
│   └── jsonl.py         # JSONL file parsing
└── cli.py               # Click CLI entry points

Riva is modular by design. New agent detectors can be added without changing the core.

---

Development

Setup

git clone https://github.com/sarkar-ai/riva.git
cd riva
python -m venv .venv
source .venv/bin/activate
pip install -e ".[test]"

Running tests

pytest                                    # All tests
pytest --cov=riva --cov-report=term-missing  # With coverage
pytest tests/test_cli.py                  # Specific file

Linting

pip install ruff
ruff check src/ tests/
ruff format --check src/ tests/

Type checking

pip install mypy types-psutil
mypy src/riva/ --ignore-missing-imports --no-strict

---

Release Process

1. Update version in pyproject.toml
2. Update HISTORY.md with changes
3. Run full test suite: pytest --cov=riva
4. Build the package: python -m build
5. Verify: twine check dist/*
6. Create a git tag: git tag v0.x.x
7. Push with tags: git push --tags
8. Create a GitHub Release — this triggers automatic PyPI publishing

Manual publish (if needed)

python -m build
twine upload dist/*

---

Uninstall

pip uninstall riva-agent

Or use the uninstall script:

curl -fsSL https://raw.githubusercontent.com/sarkar-ai/riva/main/uninstall.sh | bash

---

Early Stage Project

Riva is early-stage and evolving rapidly.

Expect:

• Rapid iteration
• API changes
• Active design discussions

Feedback is highly encouraged.

---

Philosophy

If you cannot see what an agent is doing, you cannot trust it.

Riva exists to make local AI agents inspectable, understandable, and safe.

---

Contributing

We welcome contributions and design discussions.

See CONTRIBUTING.md for guidelines.

---

License

MIT — see LICENSE for details.