Remote Shell

Troubleshoot a managed Windows or macOS device from a persistent, recorded terminal in the portal: Windows PowerShell or the Command Prompt on Windows, zsh or bash on a Mac, as the system (even when nobody is signed in) or as the signed-in user.

WindowsmacOSAccount Owners and Admins can open a shell, and MSP Technicians can when the Account Owner allows it; only the Account Owner can replay recordings

In short

  • An Account Owner or tenant Admin must enable Remote Shell in Settings first. MSP Technicians can open shells only after the Account Owner switches on Allow MSP Technicians to use remote shell and the file manager; Read Only and MSP Read Only users cannot.
  • Windows 10 or Windows Server 2019 build 17763 or newer, or a Mac the agent supports. On a Mac the system context is root.
  • Everything typed and printed is recorded, including passwords, and kept for 30 days.
  • There is no consent prompt, and the user notification is off by default.
  • A session ends after five minutes with no input or output, and after one hour in any case.

Requirements and access

Access
An Account Owner or tenant Admin must enable Remote Shell in Settings and click Save Changes. MSP Technicians can open shells only once the Account Owner has also switched on Allow MSP Technicians to use remote shell and the file manager, which is off by default and covers every tenant in the account. Read Only and MSP Read Only users cannot.
Device
A remote-shell-capable agent and a successful check-in after it updated. Windows needs Windows 10 or Windows Server 2019 build 17763 or newer. A Mac needs no permission approval to open a shell, unlike remote desktop. To reach the folders macOS protects (Desktop, Documents, Downloads, Mail and similar), turn on pckgr-agent under System Settings > Privacy & Security > Full Disk Access at the Mac, or grant it with a privacy profile from your MDM. Without it those folders answer “Operation not permitted”, as root too, and nothing is shown to the user.
Recording encryption
Must be configured by the service operator before connections are available.
Network
The terminal travels over a direct WebRTC connection between your browser and the device, the same way remote desktop does, so the same STUN and TURN servers apply. A network that blocks UDP falls back to the TURN relay over TCP or TLS on port 443; the status line shows "via relay" when that happens.

Start and end a session

  1. Open a device and choose Remote Shell.

  2. Pick the shell (Windows PowerShell or Command Prompt on Windows, zsh or bash on a Mac) and whether to run as the system or as the signed-in user.

  3. Select Connect.

    If another desktop or shell session is active, review who started it before choosing Take over. Taking over stops the previous session and its running commands.
  4. Use the terminal for interactive commands.

Run asWhat you get
SystemWorks even when nobody is signed in. Does not share the signed-in user’s profile, mapped drives or application settings. On a Mac this is root, shown as “root” on the page.
Signed-in userNeeds someone signed in on the device. Gives you their profile, drives and settings, with their ordinary (non-elevated) rights. On a Mac the shell starts in their home folder and cannot use sudo without their password.

On a Mac both shells start as login shells, so the usual startup files load and the command path is the one Terminal gives.

The tenant's Notify the signed-in user setting controls whether a notification is shown before connecting. It is off by default. There is no consent prompt, and no console window appears on the user's desktop. On a Mac the notification goes to Notification Center, where a Focus or the user's own notification settings can hide it.

Only run commands approved for this device.

Ending the session stops the shell

Typing exit, closing its tab, ending the session, losing the connection or restarting the agent stops the shell and everything it started, background jobs included. Reconnecting starts a new shell. On a Mac, a program you deliberately hand to the system (for example a launchd job) keeps running, as it would after an SSH session; use that for anything that must outlive the session.

Limits

Idle time5 minutes
Five minutes without any input or output ends the session; a command that is still printing keeps it alive.
Session length1 hour
An absolute limit on every session.
Recording size16 MiB or 100,000 frames
Reaching either ends the session with a recording-limit message.
Queued input64 KiB in the browser
A paste that exceeds this is rejected in full; the shell remains connected. Wait for the queue to drain or paste less text.
Device input queues
If the device cannot consume input and its bounded queues fill, the session ends with an input-queue message. Commands are not silently truncated or dropped.
Browser output15 seconds
If your browser stops taking output for 15 seconds, the session ends.
Pending connection90 seconds
A connection that hasn’t opened by then expires.

Troubleshooting

MessageWhat it means
“Could not establish a direct connection”No WebRTC path opened within 45 seconds, not even through the relay. Check that the device and your browser can reach the STUN and TURN servers listed under Hardened Environments.
Upgrade required, or “needs a newer agent”The device has not reported shell support. Update the agent and wait for its next check-in.
“No user is signed in on the device”You chose the signed-in user, and nobody is signed in. Run as the system instead, or wait for someone to sign in.

For application-control and endpoint-security policies, see Hardened Environments.

Recordings and audit history

The agent records every keystroke and every line of output as it happens and uploads the recording to Pckgr within about a second. If the device cannot upload for a minute, or a batch fails its integrity check, the session is ended rather than left running unrecorded.

Secrets are recorded too

All input, output and terminal size changes are recorded, including passwords or other secrets typed into the terminal.
  • Recordings are encrypted and available for 30 days from the session's start.
  • Expired recordings are removed by an hourly cleanup; lifecycle audit entries follow the normal audit policy.
  • Only the Account Owner can play recordings from the device's shell history.
  • Deleting the device, or the user who opened the session, does not delete a recording. The Account Owner finds recordings from deleted devices under Settings > Remote Access > Recordings from deleted devices.
  • A session whose agent stopped or lost its connection before it could upload the end of the session is marked Recording may be incomplete in the shell history and on playback: the last commands run may be missing. Only agents that confirm their recording when a session ends are checked; a session from an agent that does not is never marked.
  • Playback access is audited, including reads that begin partway through a recording.
  • Playback never sends commands back to the device. The input transcript can be expanded for inspection.