# n.eko
Welcome to Neko, a self-hosted virtual browser that runs in Docker and uses WebRTC technology. Neko is a powerful tool that allows you to **run a fully-functional browser in a virtual environment**, giving you the ability to **access the internet securely and privately from anywhere**. With Neko, you can browse the web, **run applications**, and perform other tasks just as you would on a regular browser, all within a **secure and isolated environment**. Whether you are a developer looking to test web applications, a **privacy-conscious user seeking a secure browsing experience**, or simply someone who wants to take advantage of the **convenience and flexibility of a virtual browser**, Neko is the perfect solution.
In addition to its security and privacy features, Neko offers the **ability for multiple users to access it simultaneously**. This makes it an ideal solution for teams or organizations that need to share access to a browser, as well as for individuals who want to use **multiple devices to access the same virtual environment**. With Neko, you can **easily and securely share access to a browser with others**, without having to worry about maintaining separate configurations or settings. Whether you need to **collaborate on a project**, access shared resources, or simply want to **share access to a browser with friends or family**, Neko makes it easy to do so.
Neko is also a great tool for **hosting watch parties** and interactive presentations. With its virtual browser capabilities, Neko allows you to host watch parties and presentations that are **accessible from anywhere**, without the need for in-person gatherings. This makes it easy to **stay connected with friends and colleagues**, even when you are unable to meet in person. With Neko, you can easily host a watch party or give an **interactive presentation**, whether it's for leisure or work. Simply invite your guests to join the virtual environment, and you can share the screen and **interact with them in real-time**.
## About
This app uses WebRTC to stream a desktop inside of a docker container, original author made this because [rabb.it](https://en.wikipedia.org/wiki/Rabb.it) went under and his internet could not handle streaming and discord kept crashing when his friend attempted to. He just wanted to watch anime with his friends ლ(ಠ益ಠლ) so he started digging throughout the internet and found a few *kinda* clones, but none of them had the virtual browser, then he found [Turtus](https://github.com/Khauri/Turtus) and he was able to figure out the rest.
Then I found [this](https://github.com/nurdism/neko) project and started to dig into it. I really liked the idea of having collaborative browser browsing together with multiple people, so I created a fork. Initially, I wanted to merge my changes to the upstream repository, but the original author did not have time for this project anymore and it got eventually archived.
## Use-cases and comparison
Neko started as a virtual browser that is streamed using WebRTC to multiple users.
- It is **not only limited to a browser**; it can run anything that runs on linux (e.g. VLC). Browser only happens to be the most popular and widely used use-case.
- In fact, it is not limited to a single program either; you can install a full desktop environment (e.g. XFCE, KDE).
- Speaking of limits, it does not need to run in a container; you could install neko on your host, connect to your X server and control your whole VM.
- Theoretically it is not limited to only X server, anything that can be controlled and scraped periodically for images could be used instead.
- Like implementing RDP or VNC protocol, where neko would only act as WebRTC relay server. This is currently only future.
Primary use case is connecting with multiple people, leveraging real time synchronization and interactivity:
- **Watch party** - watching video content together with multiple people and reacting to it (chat, emotes) - open source alternative to [giggl.app](https://giggl.app/) or [hyperbeam](https://watch.hyperbeam.com).
- **Interactive presentation** - not only screen sharing, but others can control the screen.
- **Collaborative tool** - brainstorming ideas, cobrowsing, code debugging together.
- **Support/Teaching** - interactively guiding people in controlled environment.
- **Embed anything** - embed virtual browser in your web app - open source alternative to [hyperbeam API](https://hyperbeam.com/).
- open any third-party website or application, synchronize audio and video flawlessly among multiple participants.
- request rooms using API with [neko-rooms](https://github.com/m1k1o/neko-rooms).
- [**Neko inside VR Chat**](https://github.com/jameskitt616/vrchat_streaming) - watch remote browser together with friends in VR.
Other use cases that benefit from single-user:
- **Personal workspace** - streaming containerized apps and desktops to end-users - similar to [kasm](https://www.kasmweb.com/).
- **Persistent browser** - own browser with persistent cookies available anywhere - similar to [mightyapp](https://www.mightyapp.com/).
- no state is left on the host browser after terminating the connection.
- sensitive data like cookies are not transferred - only video is shared.
- **Throwaway browser** - a better solution for planning secret parties and buying birthday gifts off the internet.
- use Tor Browser and [VPN](https://github.com/m1k1o/neko-vpn) for additional anonymity.
- mitigates risk of OS fingerprinting and browser vulnerabilities by running in container.
- **Session broadcasting** - broadcast room content using RTMP (to e.g. twitch or youtube...).
- **Session recording** - broadcast RTMP can be saved to a file using e.g. [nginx-rtmp](https://www.nginx.com/products/nginx/modules/rtmp-media-streaming/)
- have clean environment when recording tutorials.
- no need to hide bookmarks or use incognito mode.
- **Jump host** - access your internal applications securely without the need for VPN.
- **Automated browser** - you can install [playwright](https://playwright.dev/) or [puppeteer](https://pptr.dev/) and automate tasks while being able to actively intercept them.
Compared to clientless remote desktop gateway (e.g. [Apache Guacamole](https://guacamole.apache.org/) or [websockify](https://github.com/novnc/websockify) with [noVNC](https://novnc.com/)), installed with remote desktop server along with desired program (e.g. [linuxserver/firefox](https://docs.linuxserver.io/images/docker-firefox)) provides neko additionally:
- **Smooth video** because it uses WebRTC and not images sent over WebSockets.
- **Built in audio** support, what is not part of Apache Guacamole or noVNC.
- **Multi-participant control**, what is not natively supported by Apache Guacamole or noVNC.
### Supported browsers
... see [all available images](https://neko.m1k1o.net/docs/v3/installation/docker-images)
### Why neko?
I like cats 🐱 (`Neko` is the Japanese word for cat), I'm a weeb/nerd.
***But why the cat butt?*** Because cats are *assholes*, but you love them anyways.
## Multiple rooms
For neko room management software, visit [neko-rooms](https://github.com/m1k1o/neko-rooms).
It also offers [Zero-knowledge installation (with HTTPS)](https://github.com/m1k1o/neko-rooms/?tab=readme-ov-file#zero-knowledge-installation-with-https).
## Documentation
Full documentation is available at [neko.m1k1o.net](https://neko.m1k1o.net/). Key sections include:
- [Migration from V2](https://neko.m1k1o.net/docs/v3/migration-from-v2)
- [Getting Started](https://neko.m1k1o.net/docs/v3/quick-start)
- [Installation](https://neko.m1k1o.net/docs/v3/installation)
- [Examples](https://neko.m1k1o.net/docs/v3/installation/examples)
- [Configuration](https://neko.m1k1o.net/docs/v3/configuration)
- [Frequently Asked Questions](https://neko.m1k1o.net/docs/v3/faq)
- [Troubleshooting](https://neko.m1k1o.net/docs/v3/troubleshooting)
## How to Contribute
Contributions are welcome! Check the [Contributing Guide](https://neko.m1k1o.net/contributing) for details.
## Support
If you find Neko useful, consider supporting the project via [GitHub Sponsors](https://github.com/sponsors/m1k1o).
---
### Overview (`client/README.md`)
# neko client
The web client for [neko](https://github.com/m1k1o/neko): React 19 + TypeScript, built with Vite.
It speaks only the v3 API (`/api/ws` + REST).
```
client/
core/ @m1k1o/neko: the framework-free client library, its own npm package (core/README.md)
src/
main.tsx start-up: the strings, the instance (createNekoApp), the plugins, the connection, the render under
app/ the shell: App, ErrorBoundary, the #neko grid
layout/ Header, Side (the tab bar), RoomBar (members, room menu, controls, emotes)
features/ one folder per feature: video, members, controls, room-menu, emotes, settings, connect, about
plugins/ the registry (index.ts: the list, the slots, event dispatch), the contract (types.ts), chat/, filetransfer/
components/ shared pieces: IconButton, Avatar, Dialog, EachHook; ui/ holds the shadcn/ui kit (dialog, menus, popover, tabs, button, sonner)
state/ the instance (neko.ts: createNekoApp, app.ts: the GUI store and NekoApp), the provider and hooks, actions, settings, dialogs, event wiring
i18n/ i18next: initI18n(), setLang(), the loader of the locale files
lib/ cn(): class names with Tailwind conflicts resolved (clsx + tailwind-merge)
locales/ the strings, one folder per language: common.json, chat.json, files.json
assets/ images
index.css Tailwind v4: the design tokens (@theme), the global rules, the layout's breakpoint variants
```
## Layering
Dependencies point one way: `app → layout → features → components → design`, with `state`, `i18n`
and `lib` below everything but `design`. In practice:
- A feature is a folder with its component(s), styled with Tailwind classes in the markup. Other
folders import a feature by its main file with `@/` (`import { Stage } from '@/features/video/Stage'`);
only a folder's own files are imported relatively.
- Shared components know nothing about features or plugins. Nothing imports `app/`.
- Plugins import neither each other nor `features/`; the app shell and the layout reach plugins only
through the registry `@/plugins`, and features get plugin contributions passed in (they see only
the contract in `@/plugins/types`).
- The core is imported only from its entry point, `@m1k1o/neko`, never from a path into `core/`.
- State is zustand: the core's `client.store`, the GUI's `app` store (`state/app.ts`) and each plugin's
`store.ts`, all per instance (see Composition). A component gets the instance from the context
(`useClient()`, `useApp()`, `useNeko()`), selects what it renders,
`useStore(useClient().store, (s) => s.video.playing)` (`useShallow` for several fields; the core's
`selectControlling`, `selectIsAdmin`, `selectSession` for the computed values), and re-renders only
when that value changes. Everything outside React takes the instance as its first argument, reads
`store.getState()` and writes `store.setState()` with a new object, never in place.
- Where two layers must talk without importing each other, there is a store or a signal in `state/`:
the room's event lines ("bob took the controls") are emitted on `state/bus.ts` and shown by the chat
plugin; `logout` is a bus signal every store with per-session data listens to.
`npm run check` enforces this: `eslint.config.js` holds one `no-restricted-imports` rule set per
layer, and `tools/cycles.mjs` fails on an import cycle (type-only imports excepted).
## Composition
There is no global client. `createNekoApp()` (`src/state/neko.ts`) makes one instance of the GUI, a
`NekoApp` (`src/state/app.ts`): the `NekoClient` (WebRTC transport, `autologin`, `autoconnect`,
`autoplay` from the viewer settings), its input `Overlay`, the GUI store `app` and the `bus`, with the
event wiring (server events to event lines and toasts, `state/events.ts`) and the settings (stored
and from the URL, `state/settings.ts`) applied. `main.tsx` composes the page in the order the pieces
need:
```tsx
const ready = initI18n(plugins.map((p) => p.ns)) // the strings of the active language
const neko = createNekoApp() // the client, its wiring, the settings
initPlugins(neko) // the slots, the event dispatch, each plugin's init
ready.then(() => {
neko.client.setUrl(location.href) // the connection: resume a saved session and connect
createRoot(root).render(
,
)
})
```
`` (`src/state/provider.tsx`) puts the instance in a React context; a component reads it
with `useNeko()` (the whole `NekoApp`), `useClient()`, `useApp()` (the GUI store) and `useActions()`
(`state/actions.ts`, the room actions bound to the instance), and the rest, `setSetting(neko, ...)`,
`ask(app, ...)`, `api(neko, ...)`, a plugin's `store(neko)`, takes it as the first argument. Two
instances on one page share nothing but the page (the strings, the URL parameters, `localStorage`).
To embed the GUI in another React app, compose the same pieces and render `` under a provider
(`?embed=1` and `?cast=1` on the page's URL still give the video-only layouts, for an iframe or a kiosk):
```tsx
import { initI18n } from '@/i18n'
import { plugins, initPlugins } from '@/plugins'
import { createNekoApp } from '@/state/neko'
import { NekoProvider } from '@/state/provider'
import { App } from '@/app/App'
await initI18n(plugins.map((p) => p.ns))
const neko = createNekoApp()
initPlugins(neko)
neko.client.setUrl('https://neko.example.com/')
export const Room = () => (
)
```
## Design
Styling is Tailwind v4 (`tailwindcss`, `@tailwindcss/vite`): the classes are in the markup, there is no
stylesheet per component. `src/index.css` is the whole of the CSS:
- **Tokens**: an `@theme` block with the values of the previous SCSS variables under the same names, so
`$background-primary` is `--color-background-primary` and the utility `bg-background-primary`;
`$text-normal` is `text-text-normal`, `$style-primary` is `bg-style-primary` / `text-style-primary`,
`$elevation-high` is `shadow-elevation-high`, `$side-width` / `$menu-height` / `$controls-height` are
`w-side` / `h-menu` / `h-controls`, `$text-size` is `text-ui`. The font is Tailwind's system stack
(`--font-sans`). Sizes are written in px where the legacy layout had px (`p-[5px]`, `h-7.5`).
- **Global rules** the preflight does not have: the page's size and overflow, 14px text with line-height 1
on `body` (so `rem`, the base of Tailwind's spacing scale, stays 16px), no native video controls.
- **Breakpoints** as variants: `tablet:` (up to 1024px: the page scrolls and the side panel goes under the
video, with Tailwind's `portrait:` / `landscape:` for the split), `phone:` (up to 768px: no room bar).
- The animations (`animate-shake`, `animate-loader`, `animate-badge`) and the `slider` utility (the range
inputs).
`cn()` (`src/lib/utils.ts`, `clsx` + `tailwind-merge`) joins class names and lets the last Tailwind class
win, so a caller's `className` overrides a component's; `class-variance-authority` gives the variants.
The component kit under `src/components/ui/` is shadcn/ui on Radix, restyled with the tokens: `dialog.tsx`
(`@radix-ui/react-dialog`, the overlay and the content composed by the caller), `dropdown-menu.tsx` (a
menu from a button: the resolution list, the emote picker), `popover.tsx` (the clipboard textarea, the
emoji picker), `tabs.tsx` (the side panel), `context-menu.tsx` (the member menu: a menu opened at a
point, on `@radix-ui/react-menu`, since it is opened from the member list, a chat author and Shift+F10),
`button.tsx` (the text buttons: `primary`, `outline`, `confirm`, `cancel`) and `sonner.tsx` (the toasts,
`toast()` in `src/state/dialogs.ts`). They bring focus trapping, roving focus, Escape, outside click and
ARIA. `components.json` configures `npx shadcn add ` (the radix base); a component added
that way comes with shadcn's theme classes and is rewritten with the tokens, like the ones here.
Every icon control is `IconButton` (`src/components/IconButton.tsx`): a `
... see [all available images](https://neko.m1k1o.net/docs/v3/installation/docker-images)
