Deploying Neko

Introduction

Neko is a self-hosted virtual browser that enables real-time collaborative browsing, watch parties, and remote desktop experiences. Running a full browser in a Docker container and streaming it via WebRTC, Neko allows multiple users to view and interact with the same browser session simultaneously, making it perfect for watching videos together, collaborative research, or remote demonstrations.

Built with Go on the backend and using WebRTC for low-latency streaming, Neko provides a responsive experience that feels like local browsing. Users can take turns controlling the browser, chat with each other, and share the experience in real-time from anywhere in the world.

Key highlights of Neko:

Virtual Browser: Full Chrome or Firefox browser running in the cloud
WebRTC Streaming: Low-latency video and audio streaming
Collaborative Control: Multiple users can view, one controls at a time
Watch Parties: Perfect for watching videos together remotely
Chat Integration: Built-in chat for communication during sessions
Multiple Browser Options: Chrome, Firefox, Brave, and more
Admin Controls: Manage who can control the browser
Clipboard Sharing: Copy/paste between local and remote browsers
File Transfer: Upload and download files to/from the virtual browser

This guide walks through deploying Neko on Klutch.sh using Docker.

Why Deploy Neko on Klutch.sh

Deploying Neko on Klutch.sh provides several advantages:

Always Available: Host watch parties or collaborative sessions anytime without running servers at home.

Simplified Deployment: Push to GitHub and Klutch.sh handles the container orchestration.

Consistent Performance: Server-side rendering ensures smooth experience regardless of viewer’s hardware.

Secure Browsing: Browse through a remote browser, keeping your local machine isolated.

HTTPS by Default: Secure WebRTC connections with automatic SSL certificates.

Prerequisites

Before deploying Neko on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your configuration
Basic familiarity with Docker concepts

Understanding Neko Architecture

Neko combines several technologies:

Virtual Browser: A full browser (Chrome/Firefox) running in a virtual display.

WebRTC Server: Streams video and audio to connected clients with minimal latency.

Control Server: Manages user sessions, permissions, and browser control.

Web Interface: Clean interface for viewing, controlling, and chatting.

Preparing Your Repository

Create a GitHub repository for your Neko deployment.

Repository Structure

neko-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

FROM ghcr.io/m1k1o/neko/firefox:latest

# Environment configuration
ENV NEKO_SCREEN=1920x1080@30
ENV NEKO_PASSWORD=neko
ENV NEKO_PASSWORD_ADMIN=admin
ENV NEKO_BIND=:8080
ENV NEKO_EPR=52000-52100

EXPOSE 8080
EXPOSE 52000-52100/udp

Browser Options

Choose your preferred browser by changing the image:

ghcr.io/m1k1o/neko/firefox:latest - Firefox
ghcr.io/m1k1o/neko/chromium:latest - Chromium
ghcr.io/m1k1o/neko/google-chrome:latest - Google Chrome
ghcr.io/m1k1o/neko/brave:latest - Brave Browser
ghcr.io/m1k1o/neko/tor-browser:latest - Tor Browser

Creating the .dockerignore File

.git
.github
*.md
LICENSE
.gitignore
.DS_Store

Deploying Neko on Klutch.sh

Push Your Repository to GitHub

Initialize and push your repository with the Dockerfile to GitHub.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a project named “neko” or “virtual-browser”.

Create a New App

Create a new app and connect your GitHub repository.

Configure HTTP Traffic

Neko serves its web interface over HTTP:

Select HTTP as the traffic type
Set the internal port to 8080

Set Environment Variables

Configure the application:

Variable	Value
`NEKO_SCREEN`	`1920x1080@30` (resolution@fps)
`NEKO_PASSWORD`	Password for viewers
`NEKO_PASSWORD_ADMIN`	Password for admin/control
`NEKO_BIND`	`:8080`

Deploy Your Application

Click Deploy to build and start your Neko instance.

Access Neko

Visit https://your-app-name.klutch.sh to access the virtual browser.

Using Neko

Joining a Session

Connect to your Neko instance:

Navigate to your Neko URL
Enter display name
Enter password (viewer or admin)
Click Connect

Viewer vs Admin

Viewer Password:

Watch the screen
Participate in chat
Request control

Admin Password:

Full browser control
Grant/revoke control from others
Access admin settings

Taking Control

As admin or when granted permission:

Click the “Request Control” button
Mouse and keyboard inputs are captured
Browse as if using your local browser

Releasing Control

Click “Release Control” button
Admin can revoke your control
Control is shared sequentially, not simultaneously

Watch Parties

Hosting a Watch Party

Perfect for group viewing:

Start Neko session as admin
Navigate to streaming site
Share the URL with friends
They join as viewers
You control playback, everyone watches

Supported Platforms

Watch together on:

YouTube
Netflix (with account)
Twitch
Disney+ (with account)
Other streaming sites

Audio Streaming

Audio is streamed via WebRTC:

Browser audio is captured
Streamed to all viewers
Synchronized with video

Collaborative Browsing

Research Sessions

Browse together for:

Research projects
Product comparisons
Planning activities
Teaching and demonstrations

Rotate control between participants:

Current controller releases control
Another user requests control
Admin approves or user takes control
New controller browses while others watch

Configuration Options

Screen Resolution

Configure display settings:

NEKO_SCREEN=1920x1080@30  # Full HD at 30fps
NEKO_SCREEN=1280x720@30   # HD (lower bandwidth)
NEKO_SCREEN=2560x1440@30  # 2K (more resources)

Video Quality

Adjust streaming quality:

NEKO_VIDEO_BITRATE=3000   # kbps
NEKO_VIDEO_CODEC=vp8      # or h264

Connection Settings

Configure networking:

NEKO_ICELITE=true
NEKO_ICESERVERS='[{"urls":["stun:stun.l.google.com:19302"]}]'

Chat Features

Built-in Chat

Communicate during sessions:

Text messages
Emojis
Visible to all participants
Real-time updates

Moderation

Admin can:

Kick users
Ban users
Clear chat

Uploading Files

Send files to the virtual browser:

Use the upload interface
Files appear in the browser’s download folder
Open files from within the browser

Downloading Files

Get files from the browser:

Download within the browser
Files appear in the file list
Download to your local machine

Copy/Paste

Share clipboard between local and remote:

Enable clipboard sharing in settings
Copy text in either environment
Paste in the other

Limitations

Browser security restrictions may apply
Works best with text
Large content may be limited

Privacy and Security

Isolated Browsing

Benefits of virtual browsing:

Browse without local traces
Websites see server IP, not yours
Cookies and cache stay on server
Reset by restarting container

Session Security

Passwords protect access
HTTPS encrypts connection
Admin controls who has access

Production Best Practices

Resource Allocation

Neko requires decent resources:

CPU: Browser rendering
RAM: Browser memory usage
Network: WebRTC streaming bandwidth

Network Considerations

WebRTC may need special handling:

STUN servers for NAT traversal
TURN servers for restrictive networks
UDP ports for best performance

Multiple Sessions

For multiple simultaneous sessions:

Deploy separate instances
Each instance is one shared browser
Configure different passwords

Troubleshooting

Video Not Loading

Check WebRTC connectivity
Verify browser supports WebRTC
Try different STUN/TURN servers
Check for firewall blocking

Audio Issues

Verify browser audio permissions
Check audio is playing in virtual browser
Try different audio codec settings

High Latency

Reduce resolution/framerate
Check network bandwidth
Use closer server location
Verify STUN/TURN configuration

Cannot Connect

Verify correct password
Check deployment is running
Clear browser cache
Try different browser

Alternative Use Cases

Remote Desktop

Use as lightweight remote desktop:

Access server browser remotely
Demo websites to clients
Training and education

Kiosk Mode

Public display applications:

Digital signage
Information kiosks
Controlled browsing environments

Additional Resources

Conclusion

Deploying Neko on Klutch.sh gives you a powerful collaborative browsing platform for watch parties, remote demonstrations, and shared web experiences. The combination of low-latency WebRTC streaming and full browser functionality creates an experience that feels like browsing together in the same room.

Whether you’re hosting movie nights, conducting remote training, or just browsing the web with friends, Neko on Klutch.sh provides a reliable, always-available virtual browser that brings people together online.