Neko: Self-Hosted Remote Browse for Engineers

m1k1o/neko

At its core, m1k1o/neko is a solution that allows you to run a full-fledged web browser (like Chromium) within a Docker container. The magic here is that it makes this browser accessible remotely via WebRTC, essentially streaming its display and allowing you to control it from your own machine.

Isolated Browse Environments (Security & Testing)

Secure Browse
If you need to visit potentially untrusted websites without risking your local machine, neko provides a sandboxed environment. Any malware or malicious scripts would be confined to the Docker container.

Browser-Specific Testing
You can easily spin up multiple neko instances with different browser versions or configurations to test how your web applications behave across various environments without cluttering your local development machine. This is invaluable for QA and front-end development.

Automated Browser Tasks/Scraping

While not explicitly a headless browser automation tool like Puppeteer or Selenium, neko can be integrated into workflows where you need a visual browser for complex interactions that are difficult to script headlessly, or for tasks that require human intervention but in a remote, controlled environment. Think of it as a remote desktop for a browser.

Collaborative Browse/Demonstrations

Imagine you need to demonstrate a web application to a remote team, or collaborate on debugging a live website. With neko, multiple users could potentially connect to the same browser session (though you'd need to manage input conflicts), allowing for shared viewing and interaction.

Resource Management (Cloud/Server Environments)

Instead of running resource-intensive browsers locally, you can offload them to a powerful server or cloud instance. This is particularly useful if your local machine is resource-constrained or if you need to perform many browser-related tasks concurrently.

Accessing Geo-Restricted Content (with a VPN)

If neko is deployed on a server in a specific geographical location and combined with a VPN on that server, you could potentially access content that is geo-restricted from your current location, simulating local access from the server's perspective.

neko is designed to be self-hosted, primarily using Docker. Here's a basic guide to get it up and running

Docker
You'll need Docker installed on your server or local machine.

Basic Terminal/Command Line Knowledge
To execute Docker commands.

Pull the Docker Image
The easiest way to get neko is to pull its pre-built Docker image from Docker Hub.

docker pull m1k1o/neko:latest

Run the Docker Container
Now, you can run the container. You'll need to map ports so you can access the neko web interface.

docker run -d \
  --name neko \
  -p 8080:8080 \
  -p 5000:5000/udp \
  -e NEKO_PASSWORD=your_secure_password \
  -e NEKO_PASSWORD_ADMIN=your_secure_admin_password \
  m1k1o/neko:latest

Explanation of the command

-d
Runs the container in detached mode (in the background).

--name neko
Gives your container a memorable name.

-p 8080:8080
Maps port 8080 on your host to port 8080 in the container (this is for the web interface).

-p 5000:5000/udp
Maps UDP port 5000 for WebRTC communication. Important
WebRTC often uses a range of UDP ports. For production, you might need a wider range. Check the neko documentation for recommended port ranges.

-e NEKO_PASSWORD=your_secure_password
Sets the password for regular users to connect to the browser.

-e NEKO_PASSWORD_ADMIN=your_secure_admin_password
Sets the password for administrator access (e.g., to control settings).

m1k1o/neko:latest
Specifies the Docker image to use.

Access neko
Open your web browser and navigate to http://localhost:8080 (if running locally) or http://your_server_ip:8080. You'll be prompted for the password you set.

neko is highly configurable via environment variables. Here are a few common ones you might find useful

NEKO_SCREEN
Sets the screen resolution, e.g., 1920x1080@30 (width x height @ frame rate).

NEKO_EJECT_BUTTON
Set to true to enable an "eject" button that disconnects all users.

NEKO_IMPL_AUTO_SCALE
Set to true to enable automatic scaling of the browser resolution to fit the client's window.

You would add these to your docker run command using the -e flag, just like the passwords.

docker run -d \
  --name neko_hd \
  -p 8081:8080 \
  -p 5001:5001/udp \
  -e NEKO_PASSWORD=mybrowserpass \
  -e NEKO_PASSWORD_ADMIN=myadminpass \
  -e NEKO_SCREEN=1920x1080@60 \
  m1k1o/neko:latest

While neko itself isn't a library you'd typically import and use in your application code, you'd interact with it externally. The "sample code" here is more about how you'd orchestrate or manage neko programmatically, for instance, in a deployment script or a monitoring system.

Conceptual Python Script for Managing neko (using docker-py)

This isn't neko specific code, but rather an example of how you might programmatically control a neko instance using the Docker SDK for Python.

import docker
import time

def start_neko_container(client, container_name, password, admin_password, port, udp_port):
    """Starts a neko Docker container."""
    try:
        container = client.containers.run(
            'm1k1o/neko:latest',
            detach=True,
            name=container_name,
            ports={
                '8080/tcp': port,
                '5000/udp': udp_port
            },
            environment={
                'NEKO_PASSWORD': password,
                'NEKO_PASSWORD_ADMIN': admin_password,
                'NEKO_SCREEN': '1280x720@30' # Example screen resolution
            }
        )
        print(f"Container '{container_name}' started. ID: {container.id}")
        return container
    except docker.errors.APIError as e:
        print(f"Error starting container: {e}")
        return None

def stop_neko_container(client, container_name):
    """Stops and removes a neko Docker container."""
    try:
        container = client.containers.get(container_name)
        container.stop()
        container.remove()
        print(f"Container '{container_name}' stopped and removed.")
    except docker.errors.NotFound:
        print(f"Container '{container_name}' not found.")
    except docker.errors.APIError as e:
        print(f"Error stopping/removing container: {e}")

if __name__ == "__main__":
    client = docker.from_env()

    neko_name = "my_neko_instance"
    neko_password = "securepassword123"
    neko_admin_password = "superadminpassword"
    http_port = 8080
    webrtc_udp_port = 5000

    print("--- Starting Neko Instance ---")
    neko_container = start_neko_container(
        client, neko_name, neko_password, neko_admin_password, http_port, webrtc_udp_port
    )

    if neko_container:
        print(f"Access Neko at: http://localhost:{http_port}")
        print("Waiting for 10 seconds (for demonstration purposes)...")
        time.sleep(10)

        print("\n--- Stopping Neko Instance ---")
        stop_neko_container(client, neko_name)
    else:
        print("Failed to start Neko container.")

What this Python code does

It uses the docker-py library to interact with the Docker daemon.

start_neko_container
Demonstrates how you could programmatically launch a neko container with specific settings (name, passwords, ports, environment variables).

stop_neko_container
Shows how to stop and remove a running neko instance.

This kind of script could be part of a larger automation system (e.g., a CI/CD pipeline for testing, or a cloud orchestration script).