Neko

Neko is a self‑hosted virtual browser that runs inside Docker and streams its rendering to clients via WebRTC. From a developer’s perspective, it is essentially a headless Chromium instance exposed over a low‑latency, peer‑to‑peer connection. The application is written in Go, leveraging the chromedp library for browser automation and a custom WebRTC signalling server built on top of the pion/webrtc stack. The Go binary exposes a minimal HTTP API for session control, authentication, and media routing, while the front‑end is a lightweight React SPA that connects to the signalling server using WebSocket.

Technical Stack

• Runtime: Go 1.22 (compiled static binary)
• Browser Engine: Chromium headless via chromedp
• Real‑time Transport: WebRTC (Pion) with UDP data channels for control, RTP for audio/video
• Containerization: Official Docker image (m1k1o/neko) with optional GPU passthrough for hardware‑accelerated rendering
• Data Persistence: Optional SQLite for session logs; otherwise stateless
• Security: TLS termination on the HTTP API, JWT‑based session tokens, optional OAuth2 integration

Core Capabilities

• Multi‑Participant Control: The signalling server tracks participant roles (host, co‑control) and forwards keyboard/mouse events over a data channel. The host can grant or revoke control dynamically.
• Low‑Latency Streaming: With WebRTC’s adaptive bitrate and packet loss recovery, Neko achieves <300 ms end‑to‑end latency on typical LAN links.
• Embedded Browser API: Exposes a simple REST interface (/page, /click, /input) that can be consumed by automation frameworks like Playwright or Puppeteer, allowing developers to script interactions while still receiving real‑time visual feedback.
• Watch Party & Presentation Modes: Custom room states enable synchronized media playback and screen‑sharing with optional remote control.
• Extensibility Hooks: The Go server implements a plugin interface (neko-plugin) that allows developers to inject custom logic (e.g., URL filtering, analytics) without modifying the core.

Deployment & Infrastructure

Neko is designed for edge‑friendly deployments. A single Docker container can run on a Raspberry Pi, a cloud VM, or within Kubernetes as a statefulset. The image is lightweight (~120 MB) and includes all dependencies, eliminating the need for a separate Chromium installation. For high‑availability scenarios, you can run multiple replicas behind an NGINX ingress with session affinity to preserve WebRTC peer connections. Horizontal scaling is supported by clustering the signalling server and sharing a Redis pub/sub bus for participant state.

Integration & Extensibility

• Webhooks: The server can emit events (e.g., room.created, participant.joined) to external services via HTTP callbacks, enabling CI/CD pipelines or monitoring dashboards.
• API: A JSON‑based API allows programmatic room creation, token issuance, and session termination. Authentication can be delegated to external OAuth providers or a simple HMAC scheme.
• Plugins: Developers can write Go plugins that register new endpoints or modify browser context (e.g., injecting custom CSS/JS). The plugin system uses Go’s plugin package, making it straightforward to extend functionality without touching the core codebase.

Developer Experience

Documentation is hosted on GitHub and includes a detailed architecture diagram, API reference, and best‑practice guides for latency tuning. The community is active on Discord, where developers share custom plugins and troubleshoot deployment issues. Licensing under MIT ensures that commercial or internal use imposes no restrictions, while the open‑source nature allows full auditability of security features.

Use Cases

1. Remote Testing: QA teams can spin up isolated browser instances, share them with teammates for live debugging, and capture automated test runs via the embedded API.
2. Collaborative Development: Pair‑programming sessions where one developer runs a browser and the other controls it remotely, useful for teaching or code reviews.
3. Secure Browsing: Privacy‑conscious users can host a Neko instance behind a VPN, ensuring all traffic is isolated from their local machine.
4. Interactive Presentations: Speakers can share a live browser session with an audience, allowing participants to interact with demos in real time.
5. Watch Parties: Multiple users can watch synchronized video content while reacting via integrated chat, all through a single Neko room.

Advantages

• Performance: Near‑real‑time WebRTC streaming eliminates the lag typical of remote desktop solutions.
• Flexibility: The same engine powers both manual browsing and automated scripts, reducing tooling overhead.
• Licensing: MIT license removes commercial barriers, unlike proprietary remote‑desktop services.
• Security: Isolation in a Docker container plus optional VPN integration keeps user data off the host machine.
• Community & Extensibility: Active plugin ecosystem and webhook support make it easy to adapt Neko to niche workflows.

In summary, Neko offers developers a lightweight, low‑latency virtual browser that can be embedded in workflows, shared among teams, and extended via plugins—all while running securely inside a Docker container.