Orvima
One AI tool gets eyes and hands on the web - on your machine. Open-source, local-first browser automation MCP server: 60 tools across 9 domains, a Sentinel safety gate, local OCR/vision, Edge TTS voice, and CDP real-profile attach. Runs at 127.0.0.1.
Why Orvima
- Live viewport - frames stream to a local dashboard (
http://127.0.0.1:8301) you can watch. - Human-in-the-loop - pause/resume always; an optional fail-closed Sentinel gate holds risky actions.
- Verified steps - every mutating action confirms the DOM result before the agent proceeds.
- Local-first - cookies, sessions, and scrapes stay on your machine. Loopback only by default.
- Any brain - Claude, Cursor, Copilot, or any OpenAI-compatible model including local Ollama.
Quick start
Install from source (verified against a clean checkout):
git clone https://github.com/Sachitt-AV-08/orvima.git
cd orvima
python -m pip install -e ".[mcp]"
orvima doctor
One-line installers are also provided:
# Windows (PowerShell)
irm https://raw.githubusercontent.com/Sachitt-AV-08/orvima/main/install.ps1 | iex
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/Sachitt-AV-08/orvima/main/install.sh | sh
Try it with no browser, no internet, and no keys:
orvima run "send a message to Acme support" --mode demo
Drive your own browser:
orvima serve # dashboard + API at http://127.0.0.1:8301
orvima mcp # stdio MCP server for any AI tool
Attach to a browser you already have running (CDP):
orvima --attach http://127.0.0.1:9222 mcp
Autonomous runs need a brain - any OpenAI-compatible endpoint:
export ORVIMA_LLM_BASE=http://localhost:11434/v1 # or https://api.openai.com/v1
export ORVIMA_LLM_KEY=sk-...
export ORVIMA_LLM_MODEL=llama3.1 # default gpt-4o-mini
MCP client configuration
Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):
{
"mcpServers": {
"orvima": {
"command": "orvima",
"args": ["mcp"],
"type": "stdio"
}
}
}
Claude Code:
claude mcp add orvima orvima mcp
Cursor (.cursor/mcp.json):
{
"mcpServers": {
"orvima": {
"command": "orvima",
"args": ["mcp"],
"type": "stdio"
}
}
}
Copilot / VS Code (settings.json):
{
"mcp": {
"servers": {
"orvima": {
"command": "orvima",
"args": ["mcp"],
"type": "stdio"
}
}
}
}
To run against the offline simulator instead of a real browser, add "--mode", "demo" to args.
Feature categories (60 MCP tools)
All tools are plain dict-in/dict-out. Credentials come from arguments or environment variables, never hardcoded.
Browser tool reference
Mutating tools return {"ok": true, ...} with a verified flag. Read tools return ok: true without verified. browse_eval returns mutating instead. browse_click and browse_navigate accept optional expect_url, expect_text, expect_count (+ expect_for) polled up to expect_timeout_ms; an unmet expectation is a hard error.
Architecture overview
Everything runs on 127.0.0.1; no cloud dependency for core operation.
Safety gate (Sentinel)
Sentinel is an optional package and is not a declared dependency. When it is missing or broken the gate is fail-closed: no action can be judged, so no action is auto-approved. Modes:
Check state:
curl -s localhost:8301/api/gate/stats
# {"gate":"degraded","available":false,...} <- nothing is being judged
# {"gate":"on","available":true,...} <- judging is in force
# {"gate":"off",...} <- deliberately unattended
Key mechanisms:
- Local, no LLM, no network on the decision path. Default
classifier_mode=offdecides in ~0.1 ms via pure string matching. - Fail closed, loudly. A throwing classifier, missing policy, or timeout returns
allowed: falsewithdegraded: true- a classifier bug never becomes permission. - Approval memory. After a human approves an action, its exact signature (tool + selector/ref/url/value/text) is stored and matching actions are auto-approved without re-running the classifier. Approving "place your order" does not auto-approve "delete account".
- Strong-request override. An explicit user request can lift an outward-risk hold to allow, but can never override a destructive-risk denial.
- Revalidation. A queued approval can expire while the page changes; the gate rechecks that the referenced element has not moved and the risk has not increased before honouring it (
approval_ttldefault 300 s). - Auditable. Every decision (risk, reason, classifier output) lands in the session transcript; overrides are appended to an override log.
The gate is a classifier plus a word list - it is wrong in both directions. It reduces reading load; it does not replace judgement.
Approvals
The three run modes and what they mean for approvals:
Check the current mode at any time:
curl -s localhost:8301/api/gate/stats
# {"gate":"on","available":true,...} <- judging is in force
# {"gate":"degraded","available":false,...} <- nothing is being judged, fail-closed
# {"gate":"off",...} <- deliberately unattended
If a session appears stuck, check /api/gate/stats first. A degraded gate means Sentinel is not installed or failed to load - install it or set ORVIMA_SENTINEL=off if you intentionally want no gate.
Vision module
All vision operations are local-first: Tesseract 5.x for OCR, OpenCV for image/video processing, Pillow for image I/O. No API keys, no network calls.
- OCR: grayscale, denoise, unsharp-mask, Otsu threshold, deskew, then multi-source x multi-PSM passes; best-confidence result wins. Low-confidence output is flagged.
- Region OCR reads one rectangle (price badge, button label) instead of the whole page.
- Text find reports whether a query appears and where.
- Image describe returns dimensions, dominant colors, and edge density.
- Template match locates a template image inside a page and returns center coords.
- Face detection returns count + bounding boxes only. No identity, no recognition, no image data uploaded.
- Video: adaptive frame sampling; OCR per sampled frame; scene changes via inter-frame pixel diff.
- Multi-pass OCR tries 4 rotations x 3 modes and reports which orientation read best - use as a last resort for sideways screenshots.
- Browser-screenshot OCR: screenshots the bound browser's current page and OCRs it in one call (
vision_ocr_screenshot).
Dependencies: Tesseract binary is auto-detected from PATH and common install dirs. If missing, every tool returns a clear not available message rather than making the server fail to load. Install via winget install tesseract-ocr.tesseract on Windows or your package manager elsewhere.
CLI reference
orvima [--browser {chrome,msedge,brave,chromium}] [--attach CDP_URL] [--headless] {demo,serve,mcp,run,bench,doctor}
orvima demo- offline tour.orvima serve- local API + UI athttp://127.0.0.1:8301.orvima mcp- stdio MCP server (--mode {demo,real}).orvima run "goal"- headless agent loop (--mode,--max-steps).orvima bench- measure agent-loop task pass rate (no browser).orvima doctor- health check for browser, profile, port, LLM, MCP.
Global flags work with any subcommand. --headless is CI/pod-friendly. ORVIMA_ATTACH_TAB names a single browser tab to avoid CDP handshake stalls on busy profiles.
Contributing
Contributions are welcome. See CONTRIBUTING.md.
git clone https://github.com/Sachitt-AV-08/orvima.git
cd orvima
python -m pip install -e ".[dev,mcp]"
# Quality checks
ruff format .
ruff check .
pytest # coverage gate: 75% line
- Python 3.10+ (3.11 preferred).
- Type hints and docstrings for public functions.
- New MCP tool: create it under
src/orvima/, register in the module tool list, add tests intests/, document indocs/api.md.
Report bugs and feature requests via GitHub Issues. Include reproduction steps, environment details (OS, Python, browser), and logs.
License
MIT. Free forever. Self-host it, fork it, run it on your own boxes. See LICENSE.