# neko-rooms: room management for self-hosted n.eko browsers

> neko-rooms is a Go control plane that creates and manages n.eko browser containers on demand. It is for people who want a rabb.it-style shared browser without hand-wiring Docker for every session.

**m1k1o/neko-rooms** — Selfhosted collaborative browser - room management for n.eko

- Repository: https://github.com/m1k1o/neko-rooms
- Stars: 767 · Forks: 91
- Language: Go
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/m1k1o-neko-rooms

## The problem neko-rooms solves for self-hosted n.eko users

n.eko is a virtual browser: a Firefox, Chromium or similar container streamed to participants over WebRTC. Running one instance is straightforward. Running several, one per group, with different images, ports and lifetimes, is not. That is the gap neko-rooms fills.

The README describes it as a simple room management system for n.eko and a self hosted rabb.it alternative. The audience is the operator of a small server, not a platform team. The zero-knowledge path in the README assumes no Docker or reverse proxy experience at all: rent a VPS with a public IP running Ubuntu, point a domain at it, run the install script, and let Let's Encrypt and Traefik or NGINX handle TLS.

The value is in the word management. n.eko gives you a browser. neko-rooms gives you the lifecycle around it: creating rooms, tracking which image each room uses, and exposing them under a path prefix.

## How neko-rooms drives Docker to create rooms

The architecture is visible in docker-compose.yml and go.mod. neko-rooms runs as a container that mounts /var/run/docker.sock, so it talks to the host daemon directly through the Docker Go client (github.com/docker/docker v28.4.0). The HTTP layer is go-chi/chi with the CORS middleware, configuration comes from spf13/viper, the CLI from spf13/cobra, and metrics from the Prometheus client library.

The data flow is one-directional. The web client under client/ calls the API defined in OpenApi.yml. The server, in internal/ and pkg/, translates those calls into Docker operations: create a container from a chosen n.eko image, attach it to the network named by NEKO_ROOMS_INSTANCE_NETWORK, and publish it through the configured port range. The compose file sets NEKO_ROOMS_EPR=59000-59049, so the deployment reserves fifty ports for room traffic, and NEKO_ROOMS_MUX=true enables multiplexing on that range.

NEKO_ROOMS_NAT1TO1=127.0.0.1 is the address the browser inside the room uses to reach itself; the comment in the compose file says it must be an IP reachable from the client. NEKO_ROOMS_INSTANCE_URL is the external URL. Getting those two wrong produces rooms that start but never connect, and the compose file gives no validation for either.

Rooms are addressed under NEKO_ROOMS_PATH_PREFIX=/room/, which is how a single hostname can serve many rooms. The final binary is built into a scratch image with NEKO_ROOMS_BIND=:8080 and NEKO_ROOMS_ADMIN_STATIC=/var/www, so the static front end and the API ship as one process listening on one port.

## Installing neko-rooms and creating a first room

There are two documented paths. The automated one downloads the Traefik install script and runs it as root; the README says to follow its instructions and that it secures the deployment with Let's Encrypt.

```bash
wget -O neko-rooms-traefik.sh https://raw.githubusercontent.com/m1k1o/neko-rooms/master/traefik/install
sudo bash neko-rooms-traefik.sh
```

The manual path is to edit the variables in docker-compose.yml and bring the stack up. The compose file ships with TZ=Europe/Vienna, which you should change.

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

Before a room can be created, the images it will use must exist on the host. The README is explicit that skipping this produces Error response from daemon: No such image, and it links issue #1 for that failure.

```sh
docker pull ghcr.io/m1k1o/neko/firefox
docker pull ghcr.io/m1k1o/neko/chromium
```

With the stack running and the images pulled, you open the web interface on port 8080, pick one of the images from the room form, and create the room. The room is then reachable under the path prefix. If you want GPU-accelerated rooms, the README says to install nvidia-docker and replace the image list through NEKO_ROOMS_NEKO_IMAGES, then select GPU in the room's expert settings at creation time.

```bash
NEKO_ROOMS_NEKO_IMAGES="
  ghcr.io/m1k1o/neko/nvidia-chromium:latest
  ghcr.io/m1k1o/neko/nvidia-google-chrome:latest
  ghcr.io/m1k1o/neko/nvidia-microsoft-edge:latest
  ghcr.io/m1k1o/neko/nvidia-brave:latest
"
```

## Where neko-rooms breaks down

The Docker socket mount is the sharpest edge. Anything that can reach the neko-rooms API can ask it to create containers on your host, and the roadmap still lists add bearer token to for API as unchecked. The project ships no authentication layer of its own; the README's answer for exposure is the Traefik install path, which adds an authentication provider for the reverse proxy. If you run the plain compose file on a public IP, you have a container-spawning service behind nothing.

Image updates are manual and destructive to existing rooms. The README states that to update a n.eko image you must pull the new image and recreate every room that uses the old one. There is no upgrade button; the roadmap lists add upgrade button and auto pull images, that do not exist as unstarted items. An operator who pulls a new tag and restarts the stack will find old rooms still pinned to the old image.

Storage is opt-in and fails loudly. The README quotes the error Mounts cannot be specified because storage is disabled or unavailable and points to a separate storage tutorial. Persistent data does not work until that is configured.

Finally, the scheduling story is thin by design. The roadmap lists docker SSH / TCP support, docker swarm support and k8s support as unstarted. neko-rooms assumes one Docker daemon it can reach locally. If your infrastructure is a cluster, this is the wrong tool.

## neko-rooms compared with Kasm Workspaces

The related searches pair neko-rooms with Kasm, and the contrast is real. Kasm Workspaces is a containerized desktop and application streaming platform with its own session manager, its own images, and support for clustered deployments. It asks you to adopt its images and its control plane.

neko-rooms does neither. It is a thin manager over images published by the n.eko project under ghcr.io/m1k1o/neko/, and its whole job is to create and route those rooms. It does not define a workspace format, does not ship an application catalog, and does not manage a cluster. If you want a general-purpose streaming platform with scheduling, Kasm is the broader system. If you specifically want n.eko's WebRTC browser sharing and you want many rooms of it on one host, neko-rooms is the smaller, more targeted layer.

The trade-off is that neko-rooms inherits every constraint of the host Docker daemon it drives, while a platform like Kasm abstracts that away at the cost of a much larger install.

## Maintenance, upgrades and the Apache-2.0 licence

The repository is not archived, and the last push was on 2026-04-25. The most recent release listed is v1.6.5 on 2026-03-29, following v1.6.4 on 2025-09-17 and v1.6.3 on 2025-04-04. The cadence is roughly one or two releases a year, so plan upgrades rather than expecting continuous movement.

Upgrade cost is concentrated in the image lifecycle. Updating neko-rooms itself is two commands, and the README gives them directly: docker-compose pull followed by docker-compose up -d. Updating the browsers inside rooms is the expensive part, because each affected room has to be recreated. On a host with many long-lived rooms, that is a maintenance window, not a hot reload.

The licence is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant. The repository carries a LICENSE file at the top level. The n.eko images pulled from ghcr.io are separate artifacts with their own licensing, and the repository does not state what those terms are. If you redistribute a bundled deployment, check the image licences separately. This is a description of the licence text, not legal advice.

## Conclusion

Adopt neko-rooms if you already run Docker on a host you control and want per-room n.eko containers created on demand rather than one browser instance shared by everyone. Do not adopt it if you cannot mount the Docker socket into a container, or if you expect Kubernetes or Docker Swarm scheduling, which the roadmap still lists as unstarted. Before committing, pull every image you plan to offer and confirm the name matches the list in NEKO_ROOMS_NEKO_IMAGES, since the project documents a No such image error when a room references an image that is not present locally.

## FAQ

### What is the Neko browser that neko-rooms manages?

n.eko is a virtual browser streamed to participants, and neko-rooms is the room management system layered on top of it. The README describes neko-rooms as a self hosted rabb.it alternative and links to the n.eko repository for the browser itself.

### What is Neko web in relation to neko-rooms?

The web component is the neko-rooms front end served from the same process; the Dockerfile sets NEKO_ROOMS_ADMIN_STATIC=/var/www and the container listens on port 8080. That interface is where rooms are created and opened.

### Why does neko-rooms fail with No such image when I create a room?

The image for that room type has not been pulled onto the host. The README says you need to pull all images you want to use with neko-rooms and links issue #1 for this exact error.

### Does neko-rooms support Kubernetes or Docker Swarm?

No. The roadmap lists docker swarm support and k8s support as unchecked items, alongside docker SSH / TCP support. The shipped compose file mounts the local Docker socket and assumes one reachable daemon.

### How do I update the browser image used by an existing neko-rooms room?

Pull the new image and recreate every room that uses the old one, as the README states. There is no upgrade button; the roadmap still lists add upgrade button as an open item.

## Sources

- [Issues](https://github.com/m1k1o/neko-rooms/issues)
- [License: Apache-2.0](https://github.com/m1k1o/neko-rooms/blob/master/LICENSE)
- [m1k1o/neko-rooms on GitHub](https://github.com/m1k1o/neko-rooms)
- [README](https://github.com/m1k1o/neko-rooms/blob/master/README.md)
- [Releases](https://github.com/m1k1o/neko-rooms/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-rooms