---
name: screenconnect
description: >-
  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

```bash
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:

1. `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.
2. Push that installer via `/rmm` (download + `msiexec /i ... /qn` as SYSTEM).
3. The SC agent connects -> a session named `<name>` appears with CP1/CP2/CP3 set.
4. `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`.
