DOCSEARCHbyAlgolia
Submit Docs

n.eko

repository·master·Indexed 12 days ago

https://github.com/m1k1o/neko

A self-hosted, WebRTC-powered virtual browser and desktop streaming service that allows multiple users to interactively share and control a single Linux environment running in Docker. It supports a wide range of browsers (Firefox, Chrome, Edge, Brave, etc.) and desktop environments (XFCE, KDE), providing low-latency video and built-in audio for collaborative browsing and secure, isolated internet access.

Tokens
62.6K
Snippets
192
Records
274
Agent score
95%

What's inside n.eko

  1. What is n.eko?

    master

    n.eko is a self-hosted virtual browser and desktop environment that runs inside Docker containers. It uses WebRTC technology to stream a desktop to multiple users simultaneously, providing low-latency video and built-in audio support.

    Key capabilities include:

    • Collaborative Browsing: Multiple users can interact with the same browser session in real-time (ideal for watch parties, interactive presentations, or collaborative debugging).
    • Secure & Private Browsing: Access the internet from an isolated container, preventing sensitive data like cookies from being transferred to the host machine.
    • Application Streaming: Beyond browsers, it can run any Linux application (e.g., VLC) or full desktop environments (e.g., XFCE, KDE).
    • Embedding: You can embed the virtual browser into your own web applications using the neko-rooms API to request rooms.

  2. Overview of Neko features and use cases

    master

    Neko is an open-source, self-hosted virtual browser solution that enables multiple users to interact with a single web browser instance remotely.

    Key Capabilities

    • Multi-User Collaboration: Multiple users can interact with the same browser session simultaneously.
    • Real-time Streaming: Low-latency audio and video streaming of the browser's output.
    • Hardware Acceleration: Supports GPU acceleration for improved performance.
    • Customization: Supports configuring bookmarks, extensions, and persistent data.

    Common Use Cases

    • Watch Parties: Real-time streaming and interaction for group viewing.
    • Remote Browsing: Accessing a web browser from any device without local installation.
    • Web Development & Testing: Testing websites in a controlled, remote browser environment.
    • Cloud-Based Browsing: Securely browsing from a dedicated remote environment.

  3. Understand the neko repository structure

    master

    The neko project is organized as a monorepo. Understanding the directory structure is essential for locating backend code, frontend components, runtime configurations, and application definitions.

    Core Directories

    • server/: Backend implementation in Go.

      • server/cmd/: Contains subcommands for the server (e.g., serve, plugins).
      • server/internal/: Private packages used by the server.
      • server/pkg/: Public packages intended for use by other projects.
      • server/plugins/: Location for plugins built for the server.
      • server/dev/: Scripts for local development using Docker.

    • client/: Frontend implementation in TypeScript and Vue.js.

      • client/src/: Main source code (components and pages).
      • client/public/: Static assets like icons and images.
      • client/dev/: Scripts for local development using Docker.
      • client/tools/: Code generation tools (e.g., for emojis).

    • runtime/: Defines the execution environment, including Xorg and Pulseaudio configurations.

      • runtime/fontconfig/: Font configuration files.
      • runtime/fonts/ & runtime/icon-theme/: Placeholders for custom assets.
      • runtime/intel/ or runtime/nvidia/: Flavor-specific files for different hardware.
      • runtime/widevine-installer/: Scripts for Widevine installation.

    • apps/: Contains Dockerfiles for applications (e.g., Firefox, Chrome) that run within the neko environment.

      • Each app directory contains a Dockerfile and optionally flavor-specific Dockerfiles.
      • Note: Application images expect Supervisord configuration at /etc/neko/supervisord/<app-name>.conf.

    • utils/: Helper scripts and tools.

      • utils/docker/: A Dockerfile generator that constructs base images by concatenating multiple Dockerfiles.
      • utils/xorg-deps/: Patched or custom Xorg dependencies/drivers.

    • webpage/: The source for the project's website (neko.m1k1o.net), built with Docusaurus and TypeScript.

      • webpage/docs/: Project documentation.
      • webpage/scripts/: Scripts for generating OpenAPI and configuration docs.

  5. Configure Audio & Video Capture in Neko

    master

    Neko utilizes Gstreamer to handle audio and video capture and encoding across several core features. Understanding these capture scenarios is essential for configuring how media flows between clients and the server:

    • WebRTC Clients: Use specific Video and Audio pipelines to receive streams from the server.
    • Broadcast: Uses RTMP to send audio and video to third-party services.
    • WebRTC Fallback: Captures the display as JPEG images and serves them via HTTP using the Screencast mechanism.
    • Client Sharing: Allows clients to share their own Webcam and Microphone with the server via WebRTC.

  6. Supported platforms for Neko deployment

    master

    Neko can be deployed across various environments:

    • Linux & Docker: Recommended for easy deployment using Docker containers.
    • Cloud Services: Compatible with AWS, Azure, Google Cloud, and other providers.
    • ARM Devices: Optimized versions are available for Raspberry Pi and other low-power hardware.

  7. Understand Neko V3 Compatibility Mode

    master

    Neko V3 operates in a compatibility mode to support legacy V2 configurations.

    • Triggering Legacy Mode: Setting any single V2 configuration option automatically enables legacy mode. In this mode, V2 configuration options take precedence over V3 options.
    • Client Compatibility: The standard Neko client is not compatible with V3. To use V3 features, you must use a compatible client (e.g., demodesk/neko-client).
    • Managing Legacy Mode: You can explicitly enable or disable legacy mode using the NEKO_LEGACY environment variable.

    Warning: Do not disable legacy mode unless you are using a V3-compatible client. Once such a client is released, legacy mode will be removed from the server.

    # To explicitly enable legacy mode
NEKO_LEGACY=true

# To explicitly disable legacy mode (only if using a V3-compatible client)
NEKO_LEGACY=false

  8. Understand V2 to V3 behavioral changes and limitations

    master

    When running V2 clients on a V3 server, be aware of the following behavioral differences:

    • Lock and Mute Identity: In V3, locks are implemented as settings and do not store the session_id of the user who applied them. If a user refreshes or reconnects, the lock remains, but the user who set it will appear as Somebody.
    • Session List Ordering: Due to the order of operations in the legacy API, a client may fetch the session list before registering its own user. This causes the current user to appear as Somebody in the session list.
    • WebRTC Data Channels: V3 creates data channels on the server side, whereas V2 created them on the client side. The legacy API handler manages this by having the server listen for and accept the client's data channel, overwriting the existing V3 channel.
    • WebSocket Heartbeats: V3 uses a 10-second ping interval and a heartbeat mechanism, whereas V2 used a 60-second interval.
    • Video/Audio Customization: V3 does not support the simple built-in bitrate/FPS/hardware encoding settings from V2. Users must now manually specify pipelines for video and audio to achieve customization.

  9. WebRTC Networking Requirements and Limitations

    master

    WebRTC is a peer-to-peer protocol that requires a direct connection between the client and the server.

    Connectivity Options

    1. Public IP: Use a public IP address for the server that is reachable from the client.
    2. TURN Server: Use a TURN server to relay data if a direct connection cannot be established.

    Critical Networking Rules

    • Firewall: All specified ports (Ephemeral UDP range and Multiplexing ports) must be open on the server's firewall and reachable from the client.
    • No Reverse Proxies: WebRTC does not use HTTP. You cannot use Nginx or other standard reverse proxies to forward WebRTC traffic. If you only expose port 443, you must also expose the WebRTC ports or use a TURN server.

  10. Understand neko platform support and limitations

    master

    Neko has specific constraints regarding platform support and device optimization:

    • Supported Platforms: Only Linux is officially supported. While you can attempt to run Neko on other platforms, functionality is not guaranteed.
    • Mobile Support: Neko is not optimized for mobile devices. While best-effort support is provided, it is not a primary development priority.
    • Screen Sharing: Screen sharing is currently not within the scope of the project.

  11. Compare n.eko with clientless remote desktop gateways

    master

    Unlike traditional clientless remote desktop solutions like Apache Guacamole or noVNC (which often rely on sending images over WebSockets), n.eko provides:

    • Smooth video: Uses WebRTC for high-performance video streaming.
    • Built-in audio: Native support for audio synchronization.
    • Multi-participant control: Designed specifically for multiple users to interact with the same session simultaneously.

  12. Use Expression-Driven Configuration for Video Pipelines

    master

    You can build Gstreamer pipelines dynamically based on the current display resolution and framerate using expressions evaluated via the gval library. This is useful for automatic downscaling or upscaling.

    Available Variables:

    • width: Current display width.
    • height: Current display height.
    • fps: Current display framerate.

    Pipeline Configuration Schema:

    • width, height, fps: Expressions to determine the stream resolution and framerate.
    • gst_prefix: Custom Gstreamer elements to add before the encoder (must start with !).
    • gst_suffix: Custom Gstreamer elements to add after the encoder (must start with !).
    • gst_encoder: The name of the Gstreamer encoder element (e.g., vp8enc, x264enc).
    • gst_params: A dictionary of parameters passed directly to the encoder.
    • show_pointer: Boolean to determine if the mouse pointer should be captured.
    capture:
  video:
    pipelines:
      dynamic_pipeline:
        width: "(width / 2)"
        height: "(height / 2)"
        fps: "25"
        gst_encoder: "vp8enc"
        gst_params:
          target-bitrate: "round(3072 * 650)"
        show_pointer: true