Rterm Gateway

RTerm Gateway — Remote Control Skill

RTerm can run as a headless service. When its gateway is enabled, it opens a WebSocket JSON-RPC endpoint. Any program or agent that can open a WebSocket can drive the full RTerm feature set — no UI, no human.

Use this skill to:

• Run AI agent tasks on the gateway (agent:startTask / agent:startTaskAsync).
• Open and control terminals on SSH / WinRM / Serial / local targets and run commands.
• Transfer and edit files on any connected host.
• Manage settings, command policy, skills, memory, and scheduled automation.
• Orchestrate fleets and scheduled jobs (cron) completely headlessly.

1. How the gateway works (mental model)

Your agent / program ──WebSocket JSON-RPC──> RTerm Gateway (ws://host:17888)
                                                │
                       ┌────────────────────────┼─────────────────────────┐
                       │                        │                         │
                 AgentService            TerminalService            AutomationManager
                 (run AI tasks)          (SSH/WinRM/Serial/local)   (playbooks, cron, change MOP)
                       │                        │                         │
                 LLM + tools            run commands, files        scheduler, ledgers

• Requests are JSON-RPC: { "id": "1", "method": "<name>", "params": { ... } }.
• Responses echo the id wrapped in a gateway:response envelope:
  • success → { "type": "gateway:response", "id": "1", "ok": true, "result": { ... } }
  • error → { "type": "gateway:response", "id": "1", "ok": false, "error": { "code", "message" } }
• Events stream to you asynchronously as { "type": "gateway:event" | "gateway:raw" | "gateway:ui-update", "channel"?, "payload": ... }.

Default endpoint: ws://<host>:17888 (default port 17888, configurable).

HTTP on the same port (v3.0.2+): the gateway also serves plain HTTP on that port — GET /dashboard renders the live unified dashboard (WS-push updates in the browser, falls back to polling GET /dashboard/json, which returns the raw state). Same auth model: loopback open, remote needs a token (Authorization: Bearer, x-access-token, or ?access_token=).

Auth

• Token auth via Authorization: Bearer <token> header (or a token provided per deployment).
• Localhost bypass: connections from 127.0.0.1 / ::1 skip the token by default (allowLocalhostWithoutToken: true). If you are on the same machine as RTerm, you usually need no token.
• Optional IP allow-list (CIDR) may restrict which hosts can connect.

If a connection is rejected, you'll get a close frame with a reason — treat that as an auth/IP problem, not a protocol problem.

Bootstrapping an access token (no CLI)

There is no gybackend create-token command — token creation normally happens through the gateway's own RPC/UI, which is a chicken-and-egg problem for the first token on a headless daemon. The store is a simple JSON file at {DATA_DIR}/access-tokens.json ({schemaVersion:1, tokens:[…]}). Each record holds a scrypt hash, never the plaintext:

token      = "gys_at_" + base64url(randomBytes(24))     # the plaintext you hand out (shown once)
tokenSalt  = base64(randomBytes(16))                    # per-token salt
tokenHash  = base64(scrypt(token, salt, 32))            # stored; verified with timingSafeEqual
record     = { id: "atk_"+base64url(randomBytes(12)), name, createdAt, tokenSalt, tokenHash }

To mint the first token, write a record matching that exact algorithm into the file (mode 0600). The running backend re-reads the file on every verify(), so no restart is needed. Verify over the non-loopback interface: valid token → 200, no/bad token → 401. Tokens are accepted as Authorization: Bearer <token>, x-access-token: <token>, or ?access_token=<token> (query). To revoke, delete the record by id.

1b. Standalone neuralos daemon vs. the RTerm desktop app

The gateway is served by gybackend — the headless engine. There are two ways it runs:

• RTerm.app (desktop): embeds gybackend and spawns it in-process. Backend lives only while the app is open. Its data dir is ~/Library/Application Support/rterm.
• neuralos (npm package, npm i -g neuralos): the same gybackend engine, packaged standalone with no GUI. Runs as an always-on/headless service (e.g. a macOS LaunchAgent with RunAtLoad+KeepAlive). Its data dir is ~/.gybackend-data (override with GYBACKEND_DATA_DIR).

They are separate profiles. The app and the daemon each keep their own settings.json, access-tokens.json, gyshell-*.sqlite, skills/, memory.md. Installing neuralos gives you a fresh, empty profile — none of the GUI's connections/playbooks/schedules. To share state you either copy the data over or point one at the other (see §10a). The GUI's backend-settings file is gyshell-backend-settings.json; the daemon's equivalent is settings.json — same schema, so it maps 1:1. Preserve the daemon's own gateway block when copying (the GUI may have gateway.ws.access: "disabled", which would shut off the very gateway you're trying to reach).

Feature parity: every backend capability works in neuralos — SSH, WinRM, serial, local PTY, playbooks, MOP changes, triggers, vault, recording, observability (APM/DEM/ cloud/on-call/GitOps/cost), the full agent runtime, and all bundled plugins. The only thing absent is the desktop UI (which is a client of the gateway, not a backend feature).

Gotcha — neuralos ships without ssh2 and serialport. The npm package bundles a single bin/gybackend.cjs with no node_modules; SSH and serial are lazy, guarded external requires. The daemon starts fine, but opening an SSH tab throws ssh2 is not available in this build (… WinRM/serial/local terminals still work), and a serial tab throws "install serialport". Fix once:

cd "$(npm config get prefix)/lib/node_modules/neuralos" && npm install ssh2 serialport --no-save --omit=dev

WinRM (pure HTTP) and local PTY are unaffected.

2. The 30-second start

1. Verify the gateway is up and reachable:

   node scripts/rterm-gw.mjs --url ws://127.0.0.1:17888 ping
   # -> { "pong": true, "ts": ... }
   

2. List terminals / sessions:

   node scripts/rterm-gw.mjs terminal-list
   node scripts/rterm-gw.mjs session-list
   

3. Run a command on a saved WinRM/SSH connection (the headline use case):

   node scripts/rterm-gw.mjs exec-winrm \
     --name "AWS-Windows-Server-1" \
     --command "powershell -NoProfile -Command \"Update-MpSignature; (Get-MpComputerStatus).AntispywareSignatureVersion\""
   

The bundled helper scripts/rterm-gw.mjs wraps the whole protocol (connect, RPC, events, waits) into subcommands. Use it directly or read it as a reference client.

3. Choosing the right method (decision guide)

Key gotcha — WinRM is command/response, not a PTY. terminal:write to a WinRM tab is a no-op (returns ok but runs nothing). For WinRM, drive commands through the agent (agent:startTask), whose tools route through the structured executeCommand path and return real output. SSH/local PTY tabs work fine with terminal:write + getBufferDelta.

4. RPC method reference (123 methods: 70 core + 52 observability:* + gateway:describe)

v3.0.0 — ask the gateway instead of reading this list. Call gateway:describe (params {}, or {category:"observability"} / {prefix:"settings:"}) to get the full, live method registry ({version, count, categories, methods:[{name,category,description,since,params}]}) straight from the source of truth. From the agent, use the list_gateway_methods tool (same category/prefix filters). The registry below is a static snapshot — gateway:describe is always current.

Params are passed as a JSON object under params. … = see source for full shape.

Gateway / session lifecycle

Agent (AI task execution)

Terminals (SSH / WinRM / Serial / local)

Filesystem (per terminal/host)

Settings, policy, skills, memory, models

Settings blocks (v2.9.6+, schema v5) — persisted + live-reloaded on settings:set (no restart), all editable in the desktop Settings UI: cost.modelPrices+cost.budgets (Settings → AI Cost), alerts.channels[] (Settings → Alerts), oncall.pagingChannels[] (Settings → On-Call), cloud.accounts[] (Settings → Cloud), agentspan.serverUrl+agentspan.authSecretRef (Settings → AgentSpan). Secrets are always secretRef pointers into the vault, never inline. Example: settings:set {"cost":{"modelPrices":{"moonshotai/kimi-k3":{"promptPer1M":3,"completionPer1M":15},"default":{"promptPer1M":0.7,"completionPer1M":2.2}},"budgets":[{"id":"monthly-all","model":"*","period":"monthly","capUsd":2500,"warnAt":0.8,"overAction":"throttle"}]}}.

Observability / SRE (v2.0.0–v2.3.1) — driven via the agent

The observability modules are wired into the backend and driven through agent:startTask (the agent reads/writes them via its built-in tools). Key capabilities to ask for:

The observability ledgers feed the unified dashboard and are driven by the agent's built-in tools — no separate RPC methods are needed beyond agent:startTask / agent:getUiMessages for these areas.

Plugins (v2.5.0+)

RTerm ships with 6 official plugins (auto-discovered on startup) plus any user plugins in ~/.gybackend-data/plugins. Plugin tools are called the same way as built-in tools — through agent:startTask.

Plugin triggers fire autonomously (e.g., patch_failure → propose-change, fraudops_pipeline_down → run-playbook, netdata_critical_alert → auto-remediation, agentspan_execution_failed → investigate/re-run, synapse_mesh_event → cross-mesh remediation, numbat_finding → isolate/kill/incident).

To install a custom plugin on a headless backend, drop the plugin folder (with a valid plugin.json + index.mjs) into {GYBACKEND_DATA_DIR}/plugins/ and restart — the PluginRegistry auto-discovers it.

4b. Observability RPC methods (v2.9.0+) — direct, no agent needed

v2.9.0 added 9 platform capabilities as backend modules; v2.9.2 exposed them as 41 first-class observability:* RPC methods on the gateway (no agent:startTask round-trip needed). v2.9.3 made the matching agent tools visible in the Tools section. These are the same methods the agent's get_metrics/manage_secret/manage_oncall/get_cost/manage_recording/manage_gitops/ manage_playbook_version/get_cloud_inventory/get_live_dashboard tools call.

Call them like any other RPC ({id, method, params}):

{"id":"1","method":"observability:costSummary","params":{"period":"daily"}}

Example — set a secret then verify it (values never come back):

./scripts/rterm-gw.mjs call observability:secretsSet '{"key":"aws-access-key","value":"AKIA…","labels":{"service":"aws"}}'
./scripts/rterm-gw.mjs call observability:secretsList '{}'
# → [{"key":"aws-access-key","labels":{"service":"aws"},"createdAt":…,"updatedAt":…}]   (no "value" field)

Example — check AI spend + gate a run:

./scripts/rterm-gw.mjs call observability:costSummary '{"period":"daily"}'
# → {"totalUsd":3.42, "byModel":[{"model":"gpt-4o","usd":3.42,…}]}
./scripts/rterm-gw.mjs call observability:costCheck '{"model":"gpt-4o"}'
# → {"action":"ok"|"warn"|"throttle"|"deny", "statuses":[…]}

Example — record + export a session:

./scripts/rterm-gw.mjs call observability:recordingStart '{"terminalId":"local-main","title":"deploy"}'
# → {"recordingId":"r-…"}
./scripts/rterm-gw.mjs call observability:recordingExportCast '{"recordingId":"r-…"}' > session.cast

Agent-tool equivalents (when you'd rather let the agent drive): get_metrics, manage_secret, manage_oncall, get_cost, manage_recording, manage_gitops, manage_playbook_version, get_cloud_inventory, get_live_dashboard, ingest_apm_spans, get_apm_summary, ingest_dem_beacon, get_dem_summary, collect_infra, manage_etw. Ask for them in userInput, e.g. "add this API key to the vault", "show my AI spend today", "page the on-call for the DB incident", "lint this playbook", "ingest these OTLP spans", "ingest this RUM beacon", "collect the k8s cluster health", "start an ETW network trace on the Windows host".

5. TerminalConfig shapes (for terminal:createTab)

// SSH
{ "type": "ssh", "id": "t1", "title": "web-01", "cols": 120, "rows": 32,
  "host": "10.0.0.5", "port": 22, "username": "deploy",
  "password": "…",                       // or "privateKey" / "privateKeyPath" / "agent"
  "algorithmsPreset": "modern|legacy|cisco", "termType": "xterm-256color|vt100" }

// WinRM (command/response — drive commands via the AGENT, not terminal:write)
{ "type": "winrm", "id": "w1", "title": "win-01", "cols": 140, "rows": 40,
  "host": "44.197.31.152", "port": 5985, "username": "Administrator",
  "password": "…", "transport": "http", "auth": "basic", "domain": "" }

// Serial
{ "type": "serial", "id": "s1", "title": "switch-console", "cols": 120, "rows": 32,
  "path": "/dev/ttyUSB0", "baudRate": 9600, "dataBits": 8, "parity": "none",
  "stopBits": 1, "flowControl": "none" }

// Local
{ "type": "local", "id": "l1", "title": "local", "cols": 120, "rows": 32,
  "cwd": "/work", "shell": "/bin/zsh" }

Saved connections already known to RTerm can be opened by asking the agent to "open the saved connection named X" (see §6), or by reading settings:get → connections.{ssh,winrm,serial} and passing the same fields to terminal:createTab.

Gotcha — terminal:createTab does NOT resolve saved-connection names or ids. It passes config straight through to the terminal service; there is no savedConnectionName / connectionId lookup. If you pass {type:"ssh", savedConnectionName:"Remote"} the tab opens with host=undefined, username=undefined and fails with Invalid username (retried in a loop). To open a saved connection over RPC you must read it from settings:get and expand it into the full inline config yourself (host/port/username/password/…). The bundled helper scripts/gy-open.mjs does exactly this (by name or id, across ssh/winrm/serial, incl. proxy/jumpHost) — see §8c.

6. Events (watching progress live)

You do not subscribe explicitly — events stream to every connected client.

For agent:startTask, watch for agent:event payloads (tool calls, streamed model text, completion). The bundled client prints events to stderr so you can observe them.

7. Command policy & autonomy

Every command the agent runs is evaluated against the command policy:

• smart — run autonomously (unless explicitly denylisted). Headless-friendly.
• standard — asks for approval on unrecognized commands. A remote client must answer with agent:replyCommandApproval ({approvalId, decision:"allow"|"deny"}).
• safe — denies unrecognized commands.

Check the mode with settings:get → commandPolicyMode. For unattended operation, either use smart mode or pre-allowlist the commands your workflow needs (settings:addCommandPolicyRule {list:"allowlist", rule:"Update-MpSignature*"}).

7a. Governance, audit & the maker/checker model (v2.7.x)

Audit trail (v2.7.1) — hash-chained, tamper-evident

Every audit-relevant event (agent runs, command evaluations, approvals, MOP changes, playbook steps, trigger firings, alert ingestions) is appended to a hash-chained audit ledger — each record carries the SHA-256 hash of the previous one, so any tampering is detectable via verify(). The evidence sealer computes a Merkle-tree root over the records → sealed, independently-verifiable evidence bundles (KLA framework domain 11).

Ask the agent: "Show the audit ledger for command X and verify the chain", or "Seal the audit ledger and produce the evidence bundle for the auditor".

AGT policy engine (v2.7.7) — governance before execution

The AGT policy engine evaluates every consequential action against a YAML policy before execution. Decisions: allow / deny / escalate (route to approval).

• Glob-style action patterns ("read" matches "read /etc/passwd"), target wildcards (prod-*), first-match-wins, case-insensitive.
• Built-in default policy: allow read/status/list; deny delete/drop/format; escalate restart/patch/deploy on prod-*; allow them otherwise.
• Drop a custom policy.yaml in the data dir to override.

Ask the agent: "Evaluate the action 'restart nginx' on target 'prod-web-01' against the governance policy" — the agent returns the decision + the matched rule + reason.

Review model / maker-checker (v2.7.8) — independent verification

The review model (a second LLM, the "checker") independently verifies the action model's (the "maker's") output on 5 dimensions: correctness, completeness, safety, compliance, and accuracy.

• Verdicts: approved / needs_revision / escalate.
• Modes: strict (block on any issue), advisory (flag but allow), auto-approve (skip review for low-risk actions).
• Fast output mode: if no reviewModelId is set in the profile, reviews are skipped entirely (zero added latency).

Configure it in the Settings UI (v2.7.9+): the profile has a Review Model dropdown ((None — skip reviews) = fast mode) and a Review Mode dropdown.

Monitor diagnostics (v2.7.6) — "why aren't stats displaying?"

monitorStatus reports exactly why monitor stats aren't displaying per terminal: publisher wired? session exists? collection stuck in-flight? terminal connected? platform detected? last-collect time? Diagnoses: terminal_not_connected, no_monitor_session, collection_stuck_in_flight, never_collected, stale_collection, publisher_not_wired.

Ask the agent: "Run monitor status diagnostics and report any terminals not collecting".

8. Bundled helper: scripts/rterm-gw.mjs

A dependency-light reference client (Node ≥18, uses ws). Subcommands:

# liveness + discovery
node scripts/rterm-gw.mjs ping
node scripts/rterm-gw.mjs terminal-list
node scripts/rterm-gw.mjs session-list
node scripts/rterm-gw.mjs settings-get

# generic RPC (escape hatch — any method)
node scripts/rterm-gw.mjs rpc --method models:getProfiles

# open a saved WinRM/SSH connection and run one command
node scripts/rterm-gw.mjs exec-winrm --name "AWS-Windows-Server-1" --command "<powershell>"

# run an AI agent task (blocking or async)
node scripts/rterm-gw.mjs agent-task --text "Update AV signatures on AWS-Windows-Server-1 and report the version"
node scripts/rterm-gw.mjs agent-task --async --text "Run the Friday cleanup playbook on group prod-web"

# read a file on a connected host
node scripts/rterm-gw.mjs fs-read --terminalId <id> --path C:\Temp\log.txt

Flags: --url (default ws://127.0.0.1:17888), --token (or RTERM_GW_TOKEN), --timeout.

See examples/ for ready-made programs.

8a. Shell one-liners with websocat (no Node, no Python)

You don't need Node or Python — the gateway is plain WebSocket + JSON, so websocat drives it from any shell. A prebuilt binary is in DrOlu/agent-tools (websocat.exe v1.14.1), or install from your package manager (brew install websocat, cargo install websocat).

One-shot RPC (reconnects each call; good for quick reads — use -n1 = close after one reply):

# ping
echo '{"id":"1","method":"gateway:ping"}' | websocat -n1 ws://127.0.0.1:17888
# -> {"type":"gateway:response","id":"1","ok":true,"result":{"pong":true,"ts":...}}

# list terminals
echo '{"id":"2","method":"terminal:list"}' | websocat -n1 ws://127.0.0.1:17888

With jq for scripting:

echo '{"id":"2","method":"terminal:list"}' \
  | websocat -n1 ws://127.0.0.1:17888 \
  | jq -r '.result.terminals[] | "\(.title) [\(.type)] \(.runtimeState)"'

Persistent session (required for agent:startTask* and for streaming gateway:events):

websocat ws://127.0.0.1:17888
# then paste JSON-RPC lines; responses + live events arrive on the same socket:
{"id":"1","method":"gateway:createSession"}
{"id":"2","method":"agent:startTaskAsync","params":{"sessionId":"<sid>","userInput":"Update AV signatures on AWS-Windows-Server-1 and report the version"}}

With a token (when not connecting from localhost):

websocat -H="Authorization: Bearer <token>" ws://rterm-host:17888

Note: websocat is line-oriented — perfect for request→response RPC and jq pipelines. For long agent tasks you must keep the socket open and read the streaming gateway:event messages yourself (or use the Node/Python client which manages that loop).

8b. Python client (websockets, no Node)

Any Python ≥3.9 agent can drive the gateway with the websockets library (pip install websockets). This is a minimal, complete client covering connect, RPC, an agent task, and event streaming:

import asyncio, json, sys
import websockets  # pip install websockets

URL = "ws://127.0.0.1:17888"   # localhost skips token auth
TOKEN = None                   # or "..."  -> Authorization: Bearer <token>

class RTermGW:
    def __init__(self):
        self._seq = 0
        self._pending = {}   # id -> asyncio.Future
        self.events = []     # async events (gateway:event / gateway:raw / ...)

    async def connect(self):
        # `websockets` renamed extra_headers -> additional_headers in v14/v15
        headers = {"Authorization": f"Bearer {TOKEN}"} if TOKEN else None
        try:
            self.ws = await websockets.connect(URL, additional_headers=headers)
        except TypeError:
            self.ws = await websockets.connect(URL, extra_headers=headers)
        self._reader = asyncio.create_task(self._read_loop())

    async def _read_loop(self):
        async for raw in self.ws:
            msg = json.loads(raw)
            if msg.get("type") == "gateway:response" or ("id" in msg and ("result" in msg or "error" in msg or "ok" in msg)):
                fut = self._pending.pop(msg.get("id"), None)
                if fut and not fut.done():
                    if msg.get("ok") is False or "error" in msg:
                        err = msg.get("error") or {}
                        fut.set_exception(RuntimeError(f"{err.get('code')}: {err.get('message')}"))
                    else:
                        fut.set_result(msg.get("result", msg))
            else:
                self.events.append(msg)

    async def rpc(self, method, params=None, timeout=60):
        self._seq += 1
        rid = f"c{self._seq}"
        fut = asyncio.get_event_loop().create_future()
        self._pending[rid] = fut
        await self.ws.send(json.dumps({"id": rid, "method": method, "params": params or {}}))
        return await asyncio.wait_for(fut, timeout)

async def main():
    gw = RTermGW()
    await gw.connect()
    print("ping:", await gw.rpc("gateway:ping"))

    # Run an AI agent task (blocking) and print the transcript tail
    sess = await gw.rpc("gateway:createSession")
    sid = sess["sessionId"]
    await gw.rpc("agent:startTask", {
        "sessionId": sid,
        "userInput": "Update AV signatures on the saved WinRM connection "
                     "AWS-Windows-Server-1 and report AntispywareSignatureVersion."
    }, timeout=180)
    ui = await gw.rpc("agent:getUiMessages",

…(truncated)