Files

Howard Enos 3de8b7fde3 docs(screenconnect skill): clarify end goal — GuruRMM addon, BYO alternative to GuruConnect

Replace the thin "Future: GuruRMM integration" stub with a "Why this skill exists"
section: ScreenConnect surfaces as a per-partner Integrations Center / addons-page
entry, positioned as the bring-your-own alternative to GuruConnect (a partner already
paying for ScreenConnect uses their licensed instance as the remote-access backend).
Points at the mapped plan: SPEC-024, RMM_THOUGHTS Feature 7 + Refinement 7a, the
Integrations Center roadmap item.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-23 20:51:38 -07:00

6.9 KiB

Raw Blame History

name, description

name	description
screenconnect	Manage the ACG ConnectWise ScreenConnect (Control) instance via the RESTful API Manager extension: list/inspect sessions, build PARAMETERIZED access installers (self-tag a device into the right Company/Site/Tag), run backstage commands, message guests, and update custom properties. Read-only by default; state- changing ops are gated behind --confirm. Pairs with /rmm to push the installer. Triggers: screenconnect, connectwise control, sc session, remote access agent, build screenconnect installer, run command on a screenconnect session, tag a device in screenconnect, deploy screenconnect via rmm.

name

description

screenconnect

Manage the ACG ConnectWise ScreenConnect (Control) instance via the RESTful API Manager extension: list/inspect sessions, build PARAMETERIZED access installers (self-tag a device into the right Company/Site/Tag), run backstage commands, message guests, and update custom properties. Read-only by default; state- changing ops are gated behind --confirm. Pairs with /rmm to push the installer. Triggers: screenconnect, connectwise control, sc session, remote access agent, build screenconnect installer, run command on a screenconnect session, tag a device in screenconnect, deploy screenconnect via rmm.

ScreenConnect (ConnectWise Control) Skill

Standalone CLI for the ACG ScreenConnect cloud instance (https://computerguru.screenconnect.com) via the RESTful API Manager extension. Read-only by default; writes gated behind --confirm.

Running the CLI

SC="bash $CLAUDETOOLS_ROOT/.claude/scripts/py.sh C:/claudetools/.claude/skills/screenconnect/scripts/sc.py"
$SC status                                   # auth check + instance info
$SC sessions --name "<hostname>"             # find sessions by Name
$SC session <sessionID>                       # full session detail
$SC build-installer --platform msi --name HOST --company "X" --site "Y" --tag "Z"
$SC send-command --session <id> --command "..." --confirm
$SC set-properties --session <id> --props-json '["Company","Site","Tag"]' --confirm
$SC raw --method GetSessionsByName --body '{"sessionName":""}'

Transport auto-selects httpx, else stdlib urllib (no hard dependency).

Credentials & auth (VERIFIED)

API secret is NEVER hardcoded - loaded from the SOPS vault msp-tools/screenconnect.sops.yaml field credentials.api_secret (or the SCREENCONNECT_API_SECRET env override). Auth is two headers:

CTRLAuthHeader: <raw api_secret>        (NO "Basic" prefix - Basic auth 401s)
Origin: https://computerguru.screenconnect.com

Endpoints: POST <base>/App_Extensions/2d558935-686a-4bd0-9991-07539f5fe749/Service.ashx/<Method>. Reads take a JSON object; the write methods take a positional array. Custom properties on this instance: CP1=Company, CP2=Site, CP3=Tag (up to CP8).

The deploy workflow (RMM push -> self-tag -> control)

This is the headline use case - set a device for SC and have it land correctly:

build-installer with the device's Company/Site/Tag (+ name) -> a parameterized access-installer URL (?e=Access&y=Guest&t=<name>&c=<Company>&c=<Site>&c=<Tag>). The cloud serves a pre-keyed installer; the c= params self-tag the agent.
Push that installer via /rmm (download + msiexec /i ... /qn as SYSTEM).
The SC agent connects -> a session named <name> appears with CP1/CP2/CP3 set.
sessions --name <name> -> get the sessionID -> control it (send-command, etc.).

VERIFIED end-to-end on RMM-TEST-MACHINE 2026-06-22 (installed, self-tagged Company/Site/Tag, ran a command, re-tagged via set-properties).

Method surface (probed live 2026-06-22)

Available (CLI-exposed):

Reads: GetSessionsByName (matches the Name field; "" -> blank-name sessions), GetSessionDetailsBySessionID, GetSessionBySessionID.
Writes (gated): SendCommandToSession [sessionID, command], SendMessageToSession [sessionID, message], UpdateSessionCustomProperties [sessionID, [cp1,cp2,cp3,...]], CreateSession (array; not the primary path - the installer creates access sessions).

MISSING on this extension version (NOT a deploy/control blocker):

GetSessions / GetAllSessions / GetSessionGroups (full-fleet inventory) -> "web method does not exist". Listing ALL agents needs Mike to update the RESTful API Manager extension to expose a list-all method. Until then, find sessions by Name (the installer sets the Name = machine name, so by-name lookup works).

Safety gating

send-command, send-message, set-properties refuse to run without --confirm (print what they WOULD do, exit 3). raw also refuses state-changing method names (sendcommand/updatesession/create/delete/end/transfer/install/...) without --confirm. NEVER run send-command against a production client session casually - it executes on the guest. Test against a known test machine.

Error logging

On a GENUINE functional error (auth failure, unexpected API response, transport failure) the CLI logs it to errorlog.md via log-skill-error.sh before surfacing it. It does NOT log expected/handled conditions - a missing extension method ("web method does not exist"), a rate-limit (429), the raw probe path, or selftest runs (SC_SUPPRESS_ERRORLOG=1) are skipped (see _should_log_error).

Why this skill exists: the GuruRMM addon integration (the end goal)

This skill is the verified connector prototype for a GuruRMM addon, not a one-off CLI. The end goal is to surface ScreenConnect as a first-class, per-partner entry on the GuruRMM Integrations Center / App Center ("addons page"), so a partner can wire in their OWN paid ScreenConnect instance and the RMM drives it.

Positioning - ScreenConnect is the bring-your-own alternative to GuruConnect. GuruRMM's native remote-access product is GuruConnect (consumed via its integration contract - see guru-rmm/docs/GURU_CONNECT_INTEGRATION.md). A partner who is already paying for ScreenConnect and does NOT want GuruConnect enables the ScreenConnect addon instead and uses their existing licensed instance for remote access. Same RMM surface (the "remote control" device action, embedded/ launched session), different provider behind it - selectable per partner on the addons page. It is an alternative remote-access backend, not an addition GuruConnect depends on.

What this skill proves / ports into the server: the parameterized access installer build (build-installer -> a pre-keyed URL whose repeated c= params self-tag the device into the right Company/Site/Tag with no SC-console step), the silent RMM push, and post-install control (send-command, send-message, set-properties to keep SC custom properties in sync as the RMM record changes). sc_client.build_installer_url + the control methods are what move server-side.

Where the plan is mapped (all GuruRMM-side, needs Mike's go - status Raw):

docs/specs/SPEC-024-screenconnect-auto-deploy.md - the auto-deploy mechanics (per-partner instance config, c0..c7 slot mapping, scope toggles, dispatch).
docs/RMM_THOUGHTS.md Feature 7 - parameterized deploy + control from the RMM.
docs/RMM_THOUGHTS.md Refinement 7a (Mike) - ScreenConnect as a per-partner App Center entry; generalizes to a "Remote Access" category (SC/TeamViewer/AnyDesk).
docs/FEATURE_ROADMAP.md Integrations Center - the unified addons UI surface.

Advance via RMM_THOUGHTS -> /shape-spec. Do NOT build until Mike gives the go.

Reference

Verified method/param spec, auth, installer params, and the GetSessions gap: references/api-reference.md.

6.9 KiB Raw Blame History