How oyadotai/oya-browser works
Oya is a browser automation product: users or agents start or connect a browser, ask it to perform work, inspect the result, and optionally save or replay that work as a playbook. The desktop app supplies a real, persistent browser; the server provides browser sessions, agent tools, identity and orchestration; SDK, CLI, and MCP are entry points. The README also documents routines, login/persona portability, CAPTCHA/MFA, and multiple browser providers. Some subsystem links are based on documented capabilities and tree paths because their source was not sampled.
Main entry points: loop.ts Agent task runner · routes.ts Browser routes · api.ts HTTP API · lifecycle Browser lifecycle
Components 23
Client interfaces
- TypeScript SDK
packages/sdk/src/index.ts - CLI
packages/cli/src/index.ts - MCP tools
server/src/mcp/server.ts
Desktop browser
- Desktop app
browser/main.js - Tabs and pages
browser/main/tabs/tabs.cjs - Control socket
browser/main/connection/socket.cjs
Automation
- Agent task runner
server/src/modules/agent/loop.ts - Playbooks and runs
server/src/modules/playbooks/routes.ts - Scheduled routines
server/src/modules/routines - CAPTCHA and MFA
server/src/modules/challenges
Identity and access
- Personas and logins
server/src/modules/personas/service.ts - Accounts and keys
server/src/modules/auth/routes.ts
Browser services
- HTTP API
server/src/app/api.ts - Browser routes
server/src/modules/browsers/routes.ts - Browser lifecycle
server/src/modules/browsers/lifecycle - Session gateway
server/src/modules/gateway - Browser registry
server/src/modules/browsers/registry.ts - Control plane
server/src/modules/control/service.ts - Browser providers
server/src/drivers/providers.ts
Other components
- User or agent
- Websites
- LLM service
- Slack
Connections 30
- User or agent → TypeScript SDK: uses
- User or agent → CLI: configures
- User or agent → MCP tools: invokes
- TypeScript SDK → HTTP API: sends requests
- CLI → HTTP API: configures access
- MCP tools → HTTP API: calls tools
- HTTP API → Accounts and keys: routes auth
- HTTP API → Browser routes: routes browser requests
- Browser routes → Browser lifecycle: starts and stops
- Browser routes → Browser registry: lists browsers
- Browser routes → Agent task runner: dispatches chat
- Browser routes → CAPTCHA and MFA: handles challenges
- Browser lifecycle → Session gateway: establishes sessions
- Browser lifecycle → Browser providers: selects provider
- Session gateway → Control socket: connects browser
- Desktop app → Control socket: owns connection
- Control socket → Tabs and pages: dispatches commands
- Tabs and pages → Websites: navigates and acts
- Agent task runner → Tabs and pages: controls page
- Agent task runner → LLM service: requests reasoning
- Agent task runner → Playbooks and runs: saves task
- Playbooks and runs → Agent task runner: replays steps
- User or agent → Playbooks and runs: records workflow
- User or agent → Personas and logins: manages identity
- Personas and logins → Browser lifecycle: supplies persona
- Accounts and keys → Personas and logins: scopes access
- User or agent → Scheduled routines: schedules work
- Scheduled routines → Agent task runner: runs prompt
- Control plane → Browser lifecycle: coordinates capacity
- Control plane → Slack: sends alerts