Skip to main content

​
System requirements

RequirementVersion
Bun>= 1.2.0
pnpm>= 10.0.0
GitAny recent version
GenosOS is written in pure JavaScript (ES2024+) with no TypeScript compilation. There is no build step for development — pnpm setup handles the one-time build for the bundled UI only.

​
macOS

1

Install Bun

brew install oven-sh/bun/bun
2

Install pnpm

npm install -g pnpm
3

Clone and set up

git clone https://github.com/estebanrfp/genos.git
cd genos
pnpm setup
pnpm setup runs pnpm install + pnpm build + pnpm ui:build in one step.
4

Start the gateway

bun genosos.mjs gateway
On first run, choose a provider and paste your API key. The browser opens at http://127.0.0.1:18789.
A native macOS menubar app is also available. It wraps the same gateway in a menu bar icon with one-click start/stop. See the macOS app guide for details.

​
Linux

1

Install Bun

curl -fsSL https://bun.sh/install | bash
After installation, restart your shell or source your profile:
source ~/.bashrc   # or ~/.zshrc
2

Install pnpm

npm install -g pnpm
3

Clone and set up

git clone https://github.com/estebanrfp/genos.git
cd genos
pnpm setup
4

Start the gateway

bun genosos.mjs gateway

​
Running as a systemd daemon

To keep GenosOS running in the background after logout, create a systemd user service. Create the service file at ~/.config/systemd/user/genosos.service: 
[Unit]
Description=GenosOS gateway
After=network.target

[Service]
Type=simple
WorkingDirectory=/path/to/genos
ExecStart=/home/user/.bun/bin/bun genosos.mjs gateway
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target
Enable and start it: 
systemctl --user daemon-reload
systemctl --user enable genosos
systemctl --user start genosos
Replace /path/to/genos and /home/user/.bun/bin/bun with the actual paths on your system. Run which bun to find the Bun binary location.

​
Raspberry Pi

GenosOS runs on Raspberry Pi with ARM support. The setup is the same as Linux.
Tested on Raspberry Pi 4 and Pi 5 (64-bit OS). A 64-bit Raspberry Pi OS is required — Bun does not support 32-bit ARM.
1

Install Bun (ARM)

curl -fsSL https://bun.sh/install | bash
Bun ships ARM64 binaries. Installation is the same as standard Linux.
2

Install pnpm and clone

npm install -g pnpm
git clone https://github.com/estebanrfp/genos.git
cd genos
pnpm setup
3

Start the gateway

bun genosos.mjs gateway
On Pi, the browser will not open automatically if you are connecting headlessly. Navigate to http://<pi-ip>:18789 from another device on the same network.
By default, the gateway binds to loopback (127.0.0.1) only. To reach it from another device, you must explicitly configure the gateway to bind to your network interface. Talk to the agent: "Allow access from my local network".

​
Development mode

For active development with hot reload: 
pnpm gateway:watch
This starts the gateway with bun --watch, restarting on any source file change. To skip channel connections during development (faster startup): 
GENOS_SKIP_CHANNELS=1 bun src/entry.js --dev gateway

​
Other run modes

​
One-off CLI agent

Send a single message and get a response, without starting the browser UI: 
bun genosos.mjs agent --message "your message here"

​
Terminal UI

A full terminal interface with the same capabilities as the browser UI: 
bun genosos.mjs tui
The terminal UI supports @ session autocomplete, slash commands, and inline renderers.

​
Port and network

GenosOS listens on port 18789 by default, bound to 127.0.0.1 (loopback only). The gateway refuses to start on a public interface without authentication configured. To change the port, talk to the agent: 
"Change the gateway port to 8080"

​
What pnpm setup does

The pnpm setup script runs three commands in sequence:
  1. pnpm install — installs all npm dependencies
  2. pnpm build — copies hook metadata, export templates, and writes build info
  3. pnpm ui:build — builds the bundled web UI
You only need to run this once after cloning. For subsequent code changes, no rebuild is needed — GenosOS runs directly from source.