neko - Moses Yebei

The Problem

Neko solves the problem of sharing a real, interactive desktop browser session with multiple remote users over the internet. Traditional screen-sharing tools are latency-heavy and require one user to drive. Neko replaces that with a self-hosted, containerized browser that streams over WebRTC, so each participant gets low-latency video and can control the same session simultaneously—useful for watch parties, collaborative browsing, or demoing web apps without exposing a local machine.

What This Does

This is a fork of the popular m1k1o/neko project. It runs a browser (Chromium, Firefox, Brave, etc.) inside a Docker container, captures the display via Xorg, and streams it to clients using WebRTC. The server, written in Go (server/), handles WebSocket signaling, member management, and capture. The client (client/) is a TypeScript/React app that renders the video stream and sends input events back to the server.

The repo is structured as five independent projects: server/ (Go backend), client/ (React frontend), webpage/ (marketing site), apps/ (per-browser Dockerfiles), and utils/ (helper tools). Each has its own build and dependencies. The apps/ directory contains Dockerfiles for Chromium, Firefox, Brave, KDE, and Edge, including NVIDIA variants for GPU-accelerated encoding.

How It Is Wired

Execution starts in the Go server (server/cmd/), which initializes the WebSocket handler (server/internal/websocket/handler/). The control.go file routes incoming messages—members join, send input events, and receive stream metadata. The server captures the X11 display via server/internal/capture/ and encodes it to WebRTC. The client connects via client/src/neko/index.ts, which establishes the WebSocket and WebRTC peer connection, then renders video in client/src/components/video.vue.

The import graph shows client/src/store/index.ts as a hub (Ca 2, Ce 8), importing locale, neko base, and utility modules—changes there ripple broadly. The client/src/neko/events.ts module is a pure leaf (Ca 3, Ce 0), so it's safe to modify. No circular dependencies were detected. The server's server/internal/config/capture.go has deep nesting (indentation depth 11), making it the hardest file to reason about.

How To Use It

Setup requires Docker. Build a base image, then an app image:

git clone https://github.com/moses-y/neko
cd neko
docker build -f apps/chromium/Dockerfile -t neko-chromium .
docker run -p 8080:8080 -e NEKO_PASSWORD=secret neko-chromium

Configuration lives in environment variables (e.g., NEKO_PASSWORD, NEKO_BIND) and is read by server/internal/config/. The client is served from the same container. No Makefile exists; Docker is the only supported path.

Real-World Use

A team runs Neko on a small VPS to demo a web app to remote stakeholders. They launch the Chromium container, share the URL and password, and each participant controls the same browser session. The server's server/internal/member/ tracks who's connected and enforces roles (viewer vs. controller). For GPU-accelerated encoding, they'd use apps/chromium/Dockerfile.nvidia with the NVIDIA container runtime.

Code Health & Issues

Static analysis found 33 findings (5 high, 18 medium, 10 low). High severity: deep nesting in server/internal/plugins/dependency_test.go and server/internal/config/capture.go (indentation depth 11); duplicated 6-line blocks across 46 files (e.g., apps/chromium/widevinecdm.sh); oversized files like server/pkg/xorg/keysymdef.go (2184 lines). Medium: empty catch block in client/src/neko/base.ts, high branching density in server/internal/websocket/handler/control.go (60 branch points over 177 lines). Low: unresolved TODO markers in server/internal/http/legacy/wstoclient.go (7) and utils/xorg-deps/xf86-video-dummy/v0.3.8/ltmain.sh (9).

SDLC observations: CI exists (GitHub Actions) but no workflow runs the test suite. GitHub Actions are pinned to mutable tags (@v3), not commit SHAs—a supply-chain risk. No Dependabot, no dependency vulnerability scan, and persist-credentials is not disabled on checkout. Base images use mutable tags. Test coverage is thin: 3 test files against 232 source files.

The Bottom Line

This is a functional fork of a well-known project, with a clean separation between server, client, and app images. The Go backend is solid, but the client has moderate complexity and the CI pipeline needs hardening (pinned actions, actual test execution, dependency scanning). Use it if you need a self-hosted, multi-user browser streaming solution and can invest in the operational hygiene.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

719 files

Go138
TypeScript53
Markdown45
JSON32
Vue20
YAML19

ReactVueDockerCUDA

Module dependencies

The 10 most depended-upon modules of 67, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_client_src_neko_events["events"] n1_client_src_store_index["index"] n2_client_src_neko_messages["messages"] n3_client_src_neko_types["types"] n4_client_src_plugins_anime["anime"] n5_client_src_plugins_axios["axios"] n6_client_src_plugins_i18n["i18n"] n7_client_src_plugins_log["log"] n8_client_src_plugins_neko["neko"] n9_client_src_plugins_swal["swal"] n2_client_src_neko_messages --> n0_client_src_neko_events n2_client_src_neko_messages --> n3_client_src_neko_types

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium6

low1

Pin third-party GitHub Actions to a commit SHAhigh4 occurrences

.github/workflows

docker/setup-buildx-action@v3, docker/metadata-action@v5, docker/login-action@v3, docker/build-push-action@v6

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Make CI invoke the test suite it hashigh6 occurrences

.github/workflows

6 test files, no test command in the 4 workflows read

A green check that never executed an assertion is worse than no check, because reviewers trust it.

Fix: Add a test step to the existing workflow rather than a new workflow.

Declare least-privilege permissions for GITHUB_TOKENmedium3 occurrences

.github/workflows/check_latest.yml

3 workflow(s) declare no permissions, 1 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

4 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium4 occurrences

Dockerfile.tmpl

./server/, ./client/, ./utils/xorg-deps/ (mutable tag)

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/client_build.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Expand the test suite; it cannot cover this codebasemedium3 occurrences

3 test files against 232 source files (ratio 0.013)

A reviewer reads "has tests" and assumes a safety net that covers two files out of eighty-five, which is how untested paths ship behind a green badge.

Fix: Add tests for the highest fan-in modules first.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/check_latest.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.