botroom (CLI)

Command-line entrypoint for starting a qxbot room server. Installs with the package and exposes the botroom binary.

Install

• Local dev: from this repo root, cd server && npm install. Run via npx botroom ....
• As a package: npm install -g botroom (after publishing) or npx botroom --help.

Usage

Start a server and print a preconfigured client URL:

npx botroom --name "My Room" --api-key "$OPENAI_API_KEY"

Key flags:

• --mqtt-host <url>: MQTT endpoint (default wss://mqtt.gafo.tech:8084/mqtt).
• --mqtt-options <json>: JSON passed to mqtt.connect.
• --name <string>: Label included in the generated client config.
• --system/--model/--temperature/--max-tokens/--max-tool-calls: LLM tuning.
• --api-key <key> / --base-url <url>: Override OpenAI credentials/endpoint.
• --tool/--tools <key|path>: Tool sets to enable (defaults to none). Accepts built-in keys (BOT_TOOLS, OLLAMA_TOOLS, FS_TOOLS) or paths to modules exporting tools.

Defaults: no tools enabled unless you pass --tool/--tools.

Custom tool modules

Pass file paths to load your own tools:

npx botroom --tool ./my-tools.js
npx botroom --tool BOT_TOOLS --tool ./extra-tools.js

Each module should export either a tool object or an array of tools in the OpenAI function-calling shape:

// my-tools.js
module.exports = [{
  definition: {
    type: 'function',
    function: {
      name: 'hello',
      description: 'Say hello to someone.',
      parameters: {
        type: 'object',
        properties: {
          name: { type: 'string', description: 'Who to greet.' },
        },
        required: ['name'],
        additionalProperties: false,
      },
    },
  },
  handler: async ({ name }) => ({ message: `Hello, ${name}!` }),
}];

Environment variables

No .env is auto-loaded; set env vars directly:

• MQTT_HOST (default wss://mqtt.gafo.tech:8084/mqtt)
• HEARTBEAT_MS (default 5000)
• CLIENT_URL (default http://localhost:5173)
• OPENAI_API_KEY (required unless using a different provider)
• Optional: OPENAI_MODEL, OPENAI_SYSTEM_PROMPT, OPENAI_TEMPERATURE, OPENAI_BASE_URL, MAX_HISTORY

Output

On start, the server prints a base64url ?config= link containing client/server credentials and MQTT settings. Open it in the React client (or any qxbot client) to connect to the session.