Neko Self-Hosted Virtual Browser on AWS User Guide

Overview

Neko is a free and open source virtual browser: a real desktop web browser runs inside a container on the instance, and its screen and audio are captured, encoded and streamed to viewers over WebRTC, the same low latency transport used by video calls. Anyone you give access to simply opens a URL and is looking at, and can take control of, a browser running somewhere else entirely. Nothing is installed on the viewer's machine.

Because the session is shared rather than personal, several people can watch the same browser at once and pass control between them, with a built-in chat and an admin role that can lock the room, remove members and take control back. That makes Neko useful as a collaborative browsing space, as a disposable browser that keeps risky sites off your own machine and inside an isolated container, and as a way to reach an internal web application from anywhere without publishing that application to the internet.

This cloudimg image ships the Apache-2.0 licensed Neko server, run the officially supported way as the upstream container pinned by image digest. It uses the Firefox flavour, so the browser being streamed is Mozilla Firefox under the MPL-2.0 licence and the whole stack is open source. The container is captured into the AMI, so your instance starts without downloading anything. Upstream ships fixed default passwords baked into the image (a user password and an admin password), which on a shared-control remote browser would mean anyone who found your instance could drive it; this image never runs on them. A unique user password and a unique admin password are generated on the first boot of every instance, and the browser is held back from starting until that rotation has happened. Backed by 24/7 cloudimg support.

Neko is a trademark of its respective owner and Firefox is a trademark of the Mozilla Foundation. This image is produced by cloudimg and is not affiliated with, endorsed by, or sponsored by either. It ships the free and open source software, unmodified.

What is included:

• Neko v3.1.4 (the Apache-2.0 licensed virtual browser server), pinned by image digest
• Mozilla Firefox (MPL-2.0) as the streamed browser, inside the official upstream container
• Docker Engine, with the Neko web interface published to the loopback interface only and fronted by nginx on port 80
• WebRTC media multiplexed onto a single port, 59000, for both UDP and TCP, rather than a hundred-port ephemeral range
• neko.service, neko-firstboot.service, neko-postboot.service and nginx.service as systemd units, enabled and active on boot
• A unique user password and a unique admin password generated per instance on first boot, never baked into the image
• The unauthenticated Prometheus metrics endpoint bound to loopback and blocked at the public front door
• The desktop preset to 1280x720 at 30 fps, a resolution a single-node instance can encode in software
• Ubuntu 24.04 LTS base with the latest security patches applied at build time

Before you start: the network rules Neko needs

This is the one part of deploying Neko that is easy to get wrong, so it is worth reading before you launch.

Neko needs two kinds of traffic, and they are not the same:

WebRTC media does not travel over HTTP, so it cannot be proxied through port 80. If you open only port 80, you will reach the login page and sign in successfully, and then the screen will simply stay black. That is the single most common Neko deployment problem and it is a security group issue, not a fault in the image.

You must therefore allow inbound 80/tcp, 59000/udp and 59000/tcp in the security group attached to your instance. Restrict the source to your own address range wherever you can rather than leaving it open to the internet.

Sizing: what this really needs

Neko runs a full desktop, a browser and a software video encoder on the same machine, so it is genuinely CPU hungry. The recommended instance type is m5.large (2 vCPU / 8 GiB RAM), which suits one comfortable viewer at 720p30. For several concurrent viewers, move up to m5.xlarge (4 vCPU) or lower the desktop resolution rather than expecting it to scale for free. A 4 GB swapfile is configured so the browser is not killed under memory pressure. Avoid burstable instance families for sustained sessions: video encoding exhausts CPU credits, after which the stream degrades.

Step 1 - Launch the AMI

Subscribe to the listing in AWS Marketplace, choose Continue to Launch, and launch through the EC2 console or the AWS CLI. Select the m5.large instance type, your key pair, and a security group that opens 22/tcp, 80/tcp, 59000/udp and 59000/tcp.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <your-key-pair> \
  --security-group-ids <security-group-id> \
  --subnet-id <subnet-id>

Step 2 - Connect to your instance

Connect over SSH as the default login user for your operating system variant.

ssh -i <your-key.pem> ubuntu@<instance-public-ip>

Step 3 - Confirm the services are running

The Neko stack is Docker, a one-shot first-boot unit that rotates both default passwords and resolves this instance's advertised WebRTC address, the Neko container itself, and the nginx front door. Confirm the long-running services are active:

systemctl is-active docker.service neko-firstboot.service neko.service nginx.service

All four report active. The Neko web client responds on the loopback front door:

curl -s -o /dev/null -w 'neko front door: HTTP %{http_code}\n' http://127.0.0.1/
curl -s http://127.0.0.1/health

Step 4 - Read your per-instance credentials

Two independent passwords are generated on first boot, one for the user role (watch and take control) and one for the admin role (additionally lock the room, remove members and force control). They are written to a root-only file along with the web URL and the advertised public address:

sudo cat /root/neko-credentials.txt

The credential lines read:

NEKO_USERNAME=<NEKO_USERNAME>
NEKO_USER_PASSWORD=<NEKO_USER_PASSWORD>
NEKO_ADMINNAME=<NEKO_ADMINNAME>
NEKO_ADMIN_PASSWORD=<NEKO_ADMIN_PASSWORD>
WEB_URL=<WEB_URL>
PUBLIC_IP=<PUBLIC_IP>

The upstream published defaults (user neko / admin admin) are not in use; the file is 0600 root:root. Keep it secret.

Step 5 - Sign in and start a session

Open the web interface in your browser at http://<instance-public-ip>/ and sign in. Enter a display name, then the user password to watch and take control, or the admin password to also moderate the room.

Once connected, the streamed desktop browser fills the window. Load a page in the remote browser's address bar and it renders live over WebRTC. If the screen stays black after login, the media ports (59000/udp and 59000/tcp) are not open in your security group - fix that first.

Open the side panel for chat, the member roster, stream settings and, for admins, the room controls.

Step 6 - Verify the media pipeline (optional)

The image ships a self-test that proves the appliance end to end: that both upstream default passwords are rejected, that the per-instance credentials authenticate with the correct roles, that the browser is genuinely rendering, that the GStreamer capture and encode pipeline is producing frames, that the WebRTC signalling offer advertises this instance's address on the media port, and that the metrics endpoint is loopback-only. Run it as root:

sudo /usr/local/sbin/neko-roundtrip.sh

It prints a single OK round-trip: ... line summarising every check. This is the same prover cloudimg runs during the build, so a clean line confirms the whole media path is live on your instance.

Step 7 - Confirm the metrics endpoint is closed at the front door

Neko's Prometheus metrics are unauthenticated upstream and their labels carry live session identifiers, so this image keeps them on loopback and blocks them at the public front door:

curl -s -o /dev/null -w 'metrics via front door: HTTP %{http_code} (expect 404)\n' http://127.0.0.1/metrics

Troubleshooting

• The login page loads but the screen stays black. The WebRTC media ports are not reachable. Open 59000/udp and 59000/tcp in the security group. This is the single most common issue.
• The stream is choppy or the audio breaks up. The instance is CPU-bound by software video encoding. Move to m5.xlarge, or lower the desktop resolution, or reduce the number of concurrent viewers.
• neko.service will not start. The first-boot password rotation has not completed. The application is deliberately gated on a first-boot marker and will not start on a default credential. Check journalctl -u neko-firstboot.service.
• The upstream default login neko / admin does not work. That is intentional - those defaults are rotated away on first boot and rejected. Use the credentials from /root/neko-credentials.txt.

Support

cloudimg provides 24/7 technical support by email and chat for this image: help with opening the WebRTC media ports in your security group, choosing an instance size for your viewer count, credential management, and putting the web interface behind your own TLS-terminating proxy. Neko itself is open source software licensed under Apache-2.0 (Firefox under MPL-2.0); this image ships it unmodified.