# m1k1o/neko: a self-hosted virtual browser in Docker over WebRTC

> Neko streams a browser, or a whole Linux desktop, from a container to several people at once over WebRTC. It is a good fit for watch parties, shared debugging and throwaway browsing, and a poor fit if you want a hosted API with no server of your own.

**m1k1o/neko** — A self hosted virtual browser that runs in docker and uses WebRTC.

- Repository: https://github.com/m1k1o/neko
- Website: https://neko.m1k1o.net/
- Stars: 22,395 · Forks: 1,630
- Language: Go
- License: Apache-2.0
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/m1k1o-neko

## The problem Neko solves: one browser, several people, no screen sharing

Screen sharing sends pixels of a window you already control. Neko inverts that. The browser lives inside a Docker container, and every participant receives the same live stream and can drive it with their own mouse and keyboard. The README frames the origin story plainly: the original author wanted to watch anime with friends after rabb.it shut down, and the upstream project he found was eventually archived, so m1k1o forked it.

The intended audience is narrow but real. The README lists watch parties, interactive presentations, cobrowsing and debugging, support and teaching, and embedding a virtual browser in your own web app as the multi-user cases. Single-user cases are listed too: a persistent browser whose cookies stay on the server, a throwaway browser for buying gifts or planning something private, a jump host into internal applications, and an automated browser where you can watch Playwright or Puppeteer work and intervene mid-run.

The README is explicit that the browser is only the popular case, not the boundary. Anything that runs on Linux can be streamed, VLC is the example given, and you can install a full desktop environment such as XFCE or KDE. That flexibility is the actual product: a WebRTC pipe attached to an X session.

## How the WebRTC pipeline and the container fit together

The repository splits into server/, client/, runtime/, apps/, utils/ and webpage/ at the top level, with a Dockerfile.tmpl at the root and a docker-compose.yaml next to it. The Go server is the signalling and session layer; the client is the browser-side viewer. The runtime and apps directories are where the container-side pieces live, which matches the README's claim that the container is an implementation detail rather than a requirement.

What the compose file tells you about the data flow is more useful than the directory names. Port 8080 is published for the web interface. A UDP range, 52000 to 52100, is published separately, and NEKO_WEBRTC_EPR is set to that same range. That is the media path: signalling goes over the HTTP port, and the actual audio and video travel as WebRTC over UDP. If that UDP range is not reachable from the client, the session will not negotiate media, which is the single most common deployment failure for this class of software.

The container also asks for shm_size of 2gb. Browsers use shared memory heavily, and the compose file sets this explicitly rather than leaving the Docker default, which is a signal that the default is not enough for a browser workload. Screen geometry is a container-side setting, NEKO_DESKTOP_SCREEN, defaulting to 1920x1080@30 in the sample. The README notes the theoretical path toward RDP or VNC, where Neko would act only as a WebRTC relay, but states that this is currently only future.

## Installing Neko with Docker and joining a first session

The repository ships a docker-compose.yaml, and the README points at the published images under ghcr.io/m1k1o/neko/. The compose file uses the Firefox image and calls it the default, most tested image, while noting that other browsers and applications are supported. Start by saving the service definition and bringing it up.

```yaml
services:
  neko:
    image: "ghcr.io/m1k1o/neko/firefox:latest"
    restart: "unless-stopped"
    shm_size: "2gb"
    ports:
      - "8080:8080"
      - "52000-52100:52000-52100/udp"
    environment:
      NEKO_WEBRTC_EPR: 52000-52100
      NEKO_DESKTOP_SCREEN: 1920x1080@30
      NEKO_MEMBER_MULTIUSER_USER_PASSWORD: neko
      NEKO_MEMBER_MULTIUSER_ADMIN_PASSWORD: admin
```

Then run it from the directory holding that file. The compose file does not name the service in the README text, but the service key in the file is neko, so the command is:

```bash
docker compose up -d
```

Open http://localhost:8080 in a browser. The compose file documents two accounts: the default user is neko and the default admin is admin, with the passwords set by the two NEKO_MEMBER_MULTIUSER variables above. You should land on the Neko web client and see the container's Firefox window. If you see the interface but no video, the UDP range is the first thing to check, since the compose file routes media through 52000 to 52100.

Persistence is opt-in and commented out in the file. Uncommenting the volume line mounts ./profile at /home/neko/.mozilla/firefox/profile.default, which keeps bookmarks, extensions and history across container restarts. The same comment block shows how to mount a pre-configured profile instead of an empty one.

## Where Neko is the wrong tool

The README is honest that Neko is not a clientless remote desktop gateway, and draws the comparison with Apache Guacamole itself. That distinction matters. Neko gives you a container-hosted session; it does not give you browser-based access to machines you already run. If your goal is to reach an existing Windows server or a fleet of internal hosts, the container is an obstacle, not a feature.

The multi-user model is also not access control in the sense an administrator usually means. Everyone in the room shares one session and one set of cookies. The README presents the single-user persistent browser as the case where sensitive data stays on the server and only video is transferred, which is a privacy property, but it also means a shared room is a shared identity. Anyone you invite sees the same logged-in state you do.

The networking requirement is the other hard edge. WebRTC over UDP does not traverse every NAT without help. The compose file only publishes ports; it does not configure a TURN server, and the README's WebRTC network documentation is the place it points to for that. A deployment behind carrier-grade NAT or a restrictive corporate firewall is likely to need infrastructure the compose file does not provide. Finally, the README describes the RDP and VNC relay mode as future work, so if that is what you need, this project does not do it today.

## Neko compared with Apache Guacamole and hyperbeam

Guacamole is the comparison the README makes itself. Guacamole is a clientless remote desktop gateway: you point it at existing machines over RDP, VNC or SSH, and it renders them in a browser. Neko goes the other way. It creates the session inside a container and streams it out, so the thing you connect to is something Neko started, not something you already had. If you need to reach a specific host, Guacamole is the right shape. If you need a disposable browser that several people can drive together, Neko is, and Guacamole is not.

The README also positions Neko as an open source alternative to hyperbeam and giggl.app for watch parties, and to the hyperbeam API for embedding, with neko-rooms named for requesting rooms over an API. The practical difference is where the session runs. Hyperbeam is a hosted service; Neko is something you run, which is why the README's own framing is about privacy and control. That control is paid for in operations: you supply the host, the UDP range, and the TURN configuration if your network needs it.

A third reference point the README raises is kasm for streaming containerized apps and desktops to end users, and mightyapp for a persistent browser available anywhere. Those are adjacent rather than identical. Neko's distinguishing feature in this group is that the same session is simultaneously interactive for multiple participants, which is what the watch party and cobrowsing cases depend on.

## Maintenance, releases and what the licence allows

The repository is not archived, and the last push was on 2026-08-05, which is the same timestamp as the v3.1.5 release. Before that, v3.1.0 landed on 2026-04-02 and v3.0.0 on 2025-04-01. The pattern is a major version roughly once a year with point releases in between, so an upgrade is not a weekly chore, but the jump from v2 to v3 was a major one and the documentation on the project site is versioned as v3. Anyone still on an older major line should expect configuration names to have moved.

Upgrade cost is mostly configuration drift. The compose file in the repository uses NEKO_WEBRTC_EPR, NEKO_DESKTOP_SCREEN and the NEKO_MEMBER_MULTIUSER_* keys, and the README links each of those to a specific documentation page rather than describing them inline. That means the authoritative reference for a given setting lives on the project site, not in the repository, and a version bump is the moment to re-read it.

The licence is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant. It also requires that you keep the licence and notice files and state significant changes. This is a description of the licence text, not legal advice; if you are redistributing Neko inside a product, read the LICENSE file at the repository root and the NOTICE requirements yourself.

## Conclusion

Adopt Neko if you can run a container on a host with a public IP or a TURN-capable network path, and you want several people sharing one browser session. Do not adopt it if you need a managed service, a mobile client, or remote desktop access to an existing machine, since the README describes a container-hosted X session, not a gateway to yours. Before rolling it out, verify that UDP 52000 to 52100 reaches the host from a client outside your LAN, and change NEKO_MEMBER_MULTIUSER_USER_PASSWORD and NEKO_MEMBER_MULTIUSER_ADMIN_PASSWORD away from their defaults, because the compose file ships them as neko and admin.

## FAQ

### What is Neko browser?

Neko is a self-hosted virtual browser that runs in Docker and streams its desktop to viewers over WebRTC. The README describes it as a way to run a fully functional browser in a virtual environment and access it securely and privately from anywhere, with multiple users able to connect to the same session at once.

### What is Neko Web?

The web client is the part you open in your own browser to view and control the containerized session. In the repository's docker-compose.yaml the interface is published on port 8080, and the default user account is neko while the default admin account is admin.

### How do I install m1k1o/neko with Docker?

Use the docker-compose.yaml from the repository, which pulls ghcr.io/m1k1o/neko/firefox:latest, publishes port 8080 and the UDP range 52000 to 52100, and sets NEKO_WEBRTC_EPR to that same range. The compose file also sets shm_size to 2gb and configures the neko and admin passwords through NEKO_MEMBER_MULTIUSER_USER_PASSWORD and NEKO_MEMBER_MULTIUSER_ADMIN_PASSWORD.

### Does m1k1o/neko only run Firefox?

No. The compose file calls Firefox the default, most tested image, but the README states Neko is not limited to a browser and can run anything that runs on Linux, such as VLC, and that you can install a full desktop environment like XFCE or KDE.

### Can several people use the same m1k1o/neko session at once?

Yes, that is the primary use case. The README lists watch parties, interactive presentations, cobrowsing and support or teaching as multi-user scenarios, and describes Neko as letting multiple users access it simultaneously.

### Is m1k1o/neko still maintained?

The repository is not archived and the last push was on 2026-08-05, which matches the v3.1.5 release. The previous releases were v3.1.0 on 2026-04-02 and v3.0.0 on 2025-04-01.

## Sources

- [Official documentation](https://neko.m1k1o.net/)
- [Official README](https://github.com/m1k1o/neko#readme)
- [Project repository](https://github.com/m1k1o/neko)
- [Release notes](https://github.com/m1k1o/neko/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/m1k1o-neko