Script Execution

---
name: "ImmyBot Script Execution"
description: >
  ImmyBot's PowerShell script library and its SYSTEM-context execution model:
  the script tool surface, the find → validate → confirm target → approve →
  execute → review workflow, parameter/timeout/execution-context options, and
  the safety rules governing this destructive, highly privileged operation.
when_to_use: >-
  When browsing, validating, or running ImmyBot PowerShell scripts on endpoints, or reviewing
  script execution history and results. Use when: immybot script, immybot powershell, run script
  immybot, immybot script execution, immybot script history, or immybot remediation script.
---

# ImmyBot Script Execution

ImmyBot ships a PowerShell script library that runs against managed
endpoints in **SYSTEM context**. This is a privileged, destructive
capability — scripts can install/uninstall software, change system
settings, access files, and reboot the machine.

## Anti-triggers

- **Installing or updating software** — ImmyBot has no "install this
  now" call, and a PowerShell installer script is exactly the
  anti-pattern the platform exists to remove; use
  `immybot-software-deployment`.
- **Running a script on an endpoint managed by another RMM** — ImmyBot
  reaches only computers enrolled in this ImmyBot instance, and ImmyBot
  is Windows-only. The same request against another fleet is
  `atera-agents`, `syncro-assets`, `superops-runbooks`,
  `ncentral-monitoring-tasks`, `connectwise-automate-scripts`, or
  `datto-rmm-jobs`.
- **A script that ran inside a reconciliation** — scripts executed by a
  session are tasks; use `immybot-maintenance-sessions`.

## API Tools

| Tool | Purpose |
|------|---------|
| `immybot_scripts_list` | List scripts with category/language/status filters |
| `immybot_scripts_get` | Full detail for one script by ID |
| `immybot_scripts_search` | Search scripts by name |
| `immybot_scripts_categories` | List available script categories |
| `immybot_scripts_validate` | Validate script syntax before running |
| `immybot_scripts_run` | Execute a script on a computer (DESTRUCTIVE) |
| `immybot_scripts_execution_history` | Past executions for a computer |
| `immybot_scripts_execution_result` | Result of one specific execution |

## Canonical Workflow

### 1. Find the script

```
immybot_scripts_search → immybot_scripts_get
```

Read the script description and confirm it matches the intended
outcome. Prefer global, vetted scripts over ad-hoc ones.

### 2. Validate syntax (for new or modified scripts)

`immybot_scripts_validate` checks PowerShell syntax without
executing anything. Always validate custom script content first.

### 3. Confirm the target

`immybot_computers_get` — confirm the computer is online and is the
correct endpoint. Running a script on the wrong machine is the most
common and most damaging mistake.

### 4. Get human approval

`immybot_scripts_run` is destructive. The MCP server returns a
confirmation warning describing SYSTEM-context risk. Surface that
warning, name the script and target computer explicitly, and obtain
operator approval before proceeding.

### 5. Execute and capture

Call `immybot_scripts_run` with the script ID, target computer ID,
optional parameters, timeout (default 30 min), and execution context
(default System).

### 6. Review the result

```
immybot_scripts_execution_result   # this run
immybot_scripts_execution_history  # the computer's run history
```

## Parameters & Timeouts

- **Parameters** — passed as a parameter object; confirm required
  parameters from `immybot_scripts_get` before running.
- **Timeout** — default 30 minutes. Long-running remediation (large
  installs, disk operations) may need a higher value.
- **Execution context** — defaults to System. Only change this if
  the script explicitly needs a user context.

## Safety Rules

- **Never** run a script without explicit human confirmation.
- **Always** name the exact script and exact computer in the
  approval request.
- Validate custom script content with `immybot_scripts_validate`
  before it ever runs.
- For fleet-wide remediation, pilot on one endpoint and review the
  execution result before expanding scope.
- Log the approver, script ID, target, and outcome for every run.

## Related Skills

- [endpoint-management](../endpoint-management/SKILL.md) — pick and verify the target computer
- [api-patterns](../api-patterns/SKILL.md) — destructive-operation confirmation pattern