rterm-backend 1.9.0

package/LICENSE.md

@@ -0,0 +1,35 @@
+# License
+
+**rterm-backend** is part of RTerm, by Hyperspace Technologies.
+
+This project is licensed under **Creative Commons Attribution-NonCommercial 4.0
+International (CC BY-NC 4.0)**.
+
+You are free to share and adapt the material for **non-commercial** purposes,
+with attribution. Commercial use requires a separate license from Hyperspace
+Technologies.
+
+Full legal text: https://creativecommons.org/licenses/by-nc/4.0/legalcode
+
+---
+
+## Third-party components
+
+rterm-backend bundles and links third-party open-source libraries. Their
+respective licenses (MIT, Apache-2.0, BSD, etc.) are retained by their owners.
+Notable bundled/linked components include:
+
+- **ssh2** (MIT) — SSH2 client
+- **node-pty** (MIT) — pseudo-terminal bindings
+- **better-sqlite3** (MIT) — SQLite bindings
+- **ws** (MIT) — WebSocket library
+- **@langchain/core, @langchain/langgraph** (MIT) — agent orchestration
+- **@modelcontextprotocol/sdk** (MIT) — Model Context Protocol
+- **web-tree-sitter, tree-sitter-bash** (MIT) — command parsing
+- **serialport** (MIT) — serial port bindings (optional)
+- **@xterm/headless** (MIT) — headless terminal model
+- **zod** (MIT) — schema validation
+- **socks** (MIT) — SOCKS proxy client
+- **uuid, diff, remeda** (MIT) — utilities
+
+Inspiration/references from [Tabby](https://github.com/Eugeny/tabby) (MIT).

package/README.md

@@ -0,0 +1,122 @@
+# rterm-backend
+
+**RTerm headless backend** — run RTerm-as-a-service, no desktop UI required. A
+single near-self-contained Node bundle that boots RTerm's full backend and
+exposes it over a **WebSocket JSON-RPC gateway**, so any program or agent can
+drive it remotely.
+
+```
+┌──────────────┐   WebSocket JSON-RPC   ┌──────────────────────────────────┐
+│ your agent / │ ◄────────────────────► │ rterm-backend (gybackend)        │
+│ program / CI │                        │  • AI agent (LLM + tools)        │
+└──────────────┘                        │  • SSH / WinRM / Serial / local  │
+                                        │  • fleet orchestration           │
+                                        │  • scheduled automation (cron)   │
+                                        │  • change management (MOP)       │
+                                        └──────────────────────────────────┘
+```
+
+## Install
+
+```bash
+npm install -g rterm-backend
+```
+
+This installs the `gybackend` CLI plus the small set of native/runtime
+dependencies (`better-sqlite3`, `node-pty`, `ssh2`, tree-sitter wasm, and
+optional `serialport`). Everything else — the AI agent, MCP SDK, SSH/WinRM/
+Serial handling, automation engine — is bundled into the single CLI file.
+
+## Run
+
+```bash
+gybackend
+```
+
+Or without a global install:
+
+```bash
+npx rterm-backend
+```
+
+On boot it prints the gateway endpoint:
+
+```
+[gybackend] Started.
+[gybackend] WebSocket RPC endpoint: ws://0.0.0.0:17888
+[gybackend] Data directory: ./.gybackend-data
+```
+
+## Configure (environment variables)
+
+| Var | Default | Meaning |
+|---|---|---|
+| `GYBACKEND_WS_ENABLE` | `1` | enable the WebSocket gateway |
+| `GYBACKEND_WS_HOST` | `0.0.0.0` | bind host (`127.0.0.1` for local-only) |
+| `GYBACKEND_WS_PORT` | `17888` | gateway port |
+| `GYBACKEND_DATA_DIR` | `./.gybackend-data` | settings, ledgers, skills, sessions |
+| `GYBACKEND_BOOTSTRAP_LOCAL_TERMINAL` | `true` | open a local shell tab on boot |
+| `GYBACKEND_TERMINAL_ID` | `local-main` | id of the bootstrap terminal |
+| `GYBACKEND_TERMINAL_TITLE` | `Local` | title of the bootstrap terminal |
+| `GYBACKEND_TERMINAL_CWD` | — | cwd of the bootstrap terminal |
+| `GYBACKEND_TERMINAL_SHELL` | — | shell of the bootstrap terminal |
+
+### Share settings with the desktop app
+
+By default the daemon uses its **own** data dir (a blank slate). To reuse the
+desktop RTerm app's settings, saved connections, and model keys, point it at
+the app's settings directory:
+
+```bash
+# macOS
+GYBACKEND_DATA_DIR="$HOME/Library/Application Support/rterm" gybackend
+# Linux
+GYBACKEND_DATA_DIR="$HOME/.config/rterm" gybackend
+# Windows
+set GYBACKEND_DATA_DIR=%APPDATA%\rterm && gybackend
+```
+
+## Drive it remotely
+
+The gateway is **WebSocket JSON-RPC**. Request `{ "id": "1", "method": "<name>",
+"params": {...} }` → response `{ "type": "gateway:response", "id": "1", "ok":
+true|false, "result"|"error" }`. Progress streams back as `gateway:event` /
+`gateway:raw` messages. Localhost connections skip token auth by default.
+
+Quick check with [`websocat`](https://github.com/vi/websocat):
+
+```bash
+echo '{"id":"1","method":"gateway:ping"}' | websocat -n1 ws://127.0.0.1:17888
+# -> {"type":"gateway:response","id":"1","ok":true,"result":{"pong":true,...}}
+```
+
+Run an AI agent task on a server:
+
+```bash
+websocat ws://127.0.0.1:17888
+{"id":"1","method":"gateway:createSession"}
+{"id":"2","method":"agent:startTaskAsync","params":{"sessionId":"<sid>","userInput":"Update AV signatures on the saved WinRM connection AWS-Windows-Server-1 and report the version"}}
+```
+
+**Full RPC reference + client libraries** (Node CLI, Python, websocat examples):
+see the [`rterm-gateway` skill](https://github.com/DrOlu/agent-skills/tree/main/skills/rterm-gateway).
+
+## What you can do with it
+
+- **AI agent tasks** — `agent:startTask` / `agent:startTaskAsync` (multi-step, tool-using)
+- **Terminals** — open/run SSH, WinRM, Serial, local tabs and send commands
+- **Files** — read/write/transfer on any connected host (`filesystem:*`)
+- **Fleet** — run a command across many servers, collect structured results
+- **Automation** — playbooks, scheduled cron jobs, config templates
+- **Change management (MOP)** — plan → approve → run with validation + automatic rollback
+- **Settings/policy** — manage connections, command policy, skills, memory, models
+
+## Requirements
+
+- **Node.js ≥ 18** on the host. Native deps (`better-sqlite3`, `node-pty`,
+  `ssh2` crypto, tree-sitter) install prebuilt binaries for common platforms;
+  on unusual platforms they build from source (needs a C/C++ toolchain).
+
+## License
+
+See `LICENSE.md`. RTerm — Hyperspace Technologies — https://github.com/DrOlu/RTerm