nickvasilescu/bot-hq

What it is

Bot HQ is an experimental TypeScript app for running a small team of AI bots you chat with. Each bot is a Hermes Agent process, and each gets its own screen on a single Orgo Linux computer. Bots can connect apps through Composio with approval gates, use xAI voice and an x_search tool, run scheduled routines, keep a task list and save files to a shared Library.

The interface is modeled on Grok Bot: finished turns collapse into a "work you can reopen" chip, and the side panel shows a live, controllable view of the bot's desktop. The app owns its own bot layer on top of Hermes gateways via /v1/responses and reaches agents over MCP; it is deliberately separate from Hermes Bot Mode, so bots do not appear in Hermes Desktop's Bots tab.

What you need before starting

A running Hermes gateway with its API server enabled, an Orgo computer (with a public URL for port 8787), and API keys for Orgo, Composio and xAI. Node.js 22 or newer is required. The first bot is the Hermes agent already living on that computer; the app only talks to its gateway and does not restart it or rewrite its settings.

Quick start: install on the Orgo computer

1. On your machine, build the app bundle: npm ci && scripts/pack.sh hq-app.tgz, then copy hq-app.tgz and scripts/install-on-computer.sh to the Orgo computer.

2. In Orgo, create a public URL for port 8787 on that computer.

3. On the computer, as root, run the installer with your public URL, computer ID, allowed email, a keys file containing XAI_API_KEY= and COMPOSIO_API_KEY= (and ORGO_API_KEY= if Hermes' .env lacks one), and optionally the main agent's Chrome debugging URL:

   PUBLIC_URL=https://<name>.orgo.dev ORGO_COMPUTER_ID=<uuid> ALLOWED_EMAILS=you@example.com \
   KEYS_FILE=/root/keys.txt PRIMARY_CDP_URL=http://127.0.0.1:9333 \
     bash install-on-computer.sh hq-app.tgz
   

   The script installs to /opt/hq, adds one supervisor program, and deletes the keys file after first install. Re-running it with a newer bundle upgrades the app while keeping data.

4. Register the app's tools with the main agent: python3 /opt/hq/app/scripts/add-hq-to-hermes.py (removes with --remove).

5. Open the public URL and sign in with Google, or generate a one-time link on the computer with bash /opt/hq/app/scripts/sign-in-link.sh you@example.com.

For local development, clone the repo, run npm ci, fill in .env from .env.example, and start the server (npm run dev -w server, API on :8787) and web app (npm run dev -w web, UI on :5173). Setting HQ_LOCAL=0 makes the server use the Orgo API instead of executing on the computer; DEV_LOGIN=1 enables an email-only sign-in for local use and must never be exposed publicly.

Constraints and limits

The project is explicitly experimental and has not had a security audit. Bots share one computer and can read each other's files. Approval cards only cover Composio write actions; browsing and shell work are not gated, and Hermes' risky-command prompts are not surfaced in the app. Orgo allows four screens per computer, so the team is capped at four bots. Using consumer model subscriptions for agents depends on the provider's terms. The app still uses the legacy name "Grokbot" in some places. Code is MIT licensed, but the bot artwork and third-party icons are excluded from that license.

HotRepo's take

The repository appeared on the new-project board on 2026-11-12 with 111 stars and 36 forks, gaining 9 stars in a roughly one-hour observed window (13:15–14:15 UTC). That sample is too short to say anything about sustained traction, and there is no all-language daily ranking recorded. What stands out technically is the opinionated split from Hermes Bot Mode: one gateway per extra bot, app-owned routines and bot-to-bot messaging, and a screen-per-bot model limited by Orgo's four-screen cap. The honest limits section — shared filesystem, ungated browser and shell — is the part a prospective deployer should weigh before connecting real apps.