Use the terminal in the remote viewer

The remote viewer has a terminal drawer, so you can work in a shell on the endpoint beside its screen. The terminal holds up to 8 tabs, each its own shell, and each tab runs as the agent’s account or as the person signed in at the endpoint. You can run saved scripts in a tab, and save the tabs as a layout that opens the next time you or your team connect. This page shows how to use each of these.

On FreeBSD and OpenBSD, which have no remote desktop, the same viewer opens as a terminal-only window.

Before you begin

• You need the command:execute permission. Without it, the viewer has no Terminal button.
• To open the viewer on a Windows, Linux, or macOS endpoint, you need what a remote desktop session needs. See Start a remote desktop session.
• The endpoint must be online, and remote_shell.enabled must be on in its policy. It is on by default. See Control terminal access.
• Every shell is recorded in the endpoint’s session transcripts.
• Closing the viewer window, or ending the session with End, ends every shell in the terminal.

Open the terminal

On Windows, Linux, and macOS: in the viewer’s toolbar, select Terminal. The drawer opens docked at the bottom of the window, unless your viewer settings choose another side. Select Terminal again, or Close terminal in the drawer, to hide it. Hiding the drawer leaves the shells running and keeps their output.

On an endpoint that cannot share its screen: open the endpoint and select Open terminal in its page header. This works on FreeBSD, OpenBSD, and Linux without a display, and also needs remote:initiate. The viewer opens with the terminal and no screen, and its status bar says Terminal only. This endpoint does not share its screen.

On FreeBSD and OpenBSD, Commands > Console > Open terminal, and Open terminal on a ticket’s endpoint, open the same terminal-only viewer. On any other endpoint they open the standalone console window described in Open the remote console.

The first time you open the terminal in a viewer window, it loads a saved layout if there is one (see Save and load layouts). Otherwise it opens one tab with the endpoint’s default shell, running as the agent’s account. Each tab starts with a line such as Opening a bash shell on <hostname> as root. Session 1.

Work with tabs

Each tab is a separate shell with its own screen and scrollback. A tab keeps running and receiving output while another tab is showing. A dot on a hidden tab means it has printed something you have not seen.

To	Do this
Open a tab	Select New tab (the plus button), and choose a shell and an account, such as bash as root or PowerShell as a user’s name. At 8 tabs, close one first.
Rename a tab	Double-click its name, or select Tab options (the three dots) > Rename. Enter 1 to 40 characters, and press Enter. Esc cancels.
Change a tab’s shell or account	Select Tab options > Tab settings…, change Shell or Run as, and select Save and restart. The tab’s shell restarts.
Close a tab	Select the close button on the tab, shown on the active tab and when you point at a tab, or Tab options > Close tab. If its shell is running, Close this terminal? asks first, because the shell ends. Select Don’t ask again to stop asking. Closing the last tab closes the terminal.
Clear a tab	Select Clear output. Only the active tab is cleared.
Restart a tab’s shell	Select Restart session. The tab ends its shell, writes Session 1 ended., and opens session 2.

The tab strip works from the keyboard: Left, Right, Home, and End move between tabs, F2 renames the selected tab, and Delete closes it.

Recording in the terminal’s header means the session is recorded to the transcript.

Shells by operating system

Endpoint	Shells offered, default first
Windows	PowerShell, cmd
Linux	sh, bash, zsh
macOS	zsh, bash, sh
FreeBSD and OpenBSD	sh, bash, zsh

A shell the endpoint reports is not installed, such as bash on a minimal BSD system, is left out of New tab.

Tip

In a PowerShell tab, dir is Get-ChildItem, which does not accept cmd switches such as /s or /b. Open a cmd tab for them, or run cmd /c dir /s /b from PowerShell.

Run as the agent or the signed-in user

Every tab runs as one of two accounts:

• The agent’s account: SYSTEM on Windows, or root on Linux, macOS, FreeBSD, and OpenBSD. It works whether or not anyone is signed in.
• The signed-in user: the person signed in at the endpoint’s console, with their own rights and environment. Use it for anything that belongs to their session, such as their mapped drives, their profile, or their per-user settings.

A shell as the signed-in user needs all of these:

• Someone is signed in at the endpoint’s console.
• script_execution.enabled is on in the endpoint’s policy, because the shell runs as the user under the same rule as a script run as the user. See Scripts.
• The endpoint’s agent supports it. If it does not, update the agent.
• The endpoint runs Windows, Linux, or macOS. FreeBSD and OpenBSD terminals run as root only.

It needs no permission beyond command:execute. When the signed-in user is not available, the New tab entries for that account stay listed but unavailable, with the reason under them:

Reason shown	What to do
Nobody is signed in at the endpoint.	Wait for someone to sign in, or use the agent’s account.
Nothing can run as the signed-in user on this endpoint right now. Nobody may be signed in.	The same.
Script execution is disabled by policy for this endpoint, so nothing can run as the signed-in user.	Turn on script_execution.enabled in a profile that applies to the endpoint, or use the agent’s account.
This endpoint’s agent cannot open a terminal as the signed-in user. Update the agent to use it.	Update the agent.
Not available on FreeBSD. Terminals there run as root. (or OpenBSD)	Use the root terminal.

The endpoint’s agent applies the same rules before it opens the shell. A shell as the user is refused rather than opened as the agent’s account.

Dock, resize, or pop out the terminal

Select Position in the drawer to move it:

• Dock bottom, the default, Dock left, or Dock right.
• Open in new window, which moves the terminal into a browser window of its own, with its tabs and their output.

Drag the drawer’s inner edge to resize it. To choose where the drawer opens, its size, and whether it opens as each session starts, see the Terminal section of Viewer settings.

In the separate window, Position brings the terminal back into the viewer at the side you choose. Closing the separate window also brings it back. The shells belong to the viewer window, so they keep running either way, and closing the viewer window ends them.

Run a saved script

1. Select the tab to run the script in. The script runs as that tab’s account.
2. Select Scripts. The menu says which account the script runs as, and lists the approved library scripts that can run on this endpoint. With script:run_unapproved, it also lists drafts.
3. Select a script.

The script runs as a command, not as input to the shell, so it does not change the shell’s working directory or variables. The tab shows Running script "<name>" as <account>..., then the script’s output and how it finished. The command also appears in Commands > History.

Scripts appears only with both script:read and command:execute. See Scripts.

Save and load layouts

A layout is the list of tabs, each with its name, shell, account, and optional startup commands. There are two kinds of default:

Default	Who it is for	Who can save it
Endpoint default	Every technician who opens the terminal on this endpoint	Anyone with terminal:layout:manage
My default	You, on every endpoint of one operating system family: Windows, macOS, or Linux. FreeBSD and OpenBSD use your Linux default. On the MSP plan, it follows you across every client.	You, with command:execute

When you first open the terminal in a viewer window, it loads the endpoint default if one is saved, otherwise your default for the endpoint’s operating system family, otherwise a single tab.

Select Layouts in the drawer to manage them:

Item	What it does
Load endpoint default	Replaces your open tabs with the endpoint default.
Load my default	Replaces your open tabs with your default for this operating system family.
Save as my default	Saves your open tabs as your default for this operating system family. The item names the family, such as Save as my default (Windows).
Clear my default	Deletes your default for this operating system family.
Save as endpoint default	Saves your open tabs as the endpoint default. It appears only with terminal:layout:manage.
Clear endpoint default	Deletes the endpoint default. It appears only with terminal:layout:manage.

Loading a layout over running shells asks first, because every open tab closes and its shell ends. Replacing or clearing an endpoint default also asks first, because it changes what every technician gets. The result of each action is written as a line in the active tab.

Startup commands

Each tab in a layout can carry startup commands, up to 4 KB. When the tab’s shell starts or restarts, the terminal types them into the shell, one line at a time, as if you had typed them. The shell echoes them, and they are recorded in the transcript like anything else you type.

To add them, select Tab options > Tab settings…, enter them in Startup commands, and select Save. Then save the layout. Startup commands are sent only for a tab that belongs to a saved layout.

Startup commands are sent only when both of these are true:

• You hold command:execute.
• script_execution.enabled is on in the endpoint’s policy.

Otherwise the tab opens without them and shows Startup commands not sent: followed by the reason. The Layouts menu also says when startup commands are not sent on the endpoint.

Each send is recorded in the audit log with the tab name, the layout it came from, and who last saved that layout. Saving and clearing layouts are recorded too, with the full text of any startup commands. See Audit log.

Caution

Startup commands in an endpoint default run in every technician’s terminal on that endpoint, often as SYSTEM or root. Grant terminal:layout:manage only to people you trust to write commands for the whole team.

Work with Pioneer AI in the terminal

When you chat with Pioneer AI from the viewer’s Pioneer AI drawer, or from a console conversation while the viewer is open, Pioneer AI can work in shells on the endpoint. See Let Pioneer AI control a session.

Follow Pioneer AI’s shell

When Pioneer AI opens a shell on the endpoint, the terminal opens a tab named Pioneer AI and shows the shell as Pioneer AI uses it, read-only. Output appears while Pioneer AI is working on a reply. The tab is not saved in layouts.

On the tab:

• Stop stops Pioneer AI and cancels the command that is running, as Ctrl+C would. The shell stays open, the tab says Stopped by you., and Pioneer AI does nothing more until you send it a message.
• Take over stops Pioneer AI without cancelling a running command, and lets you type in its shell. The tab shows You have control. While you do, Pioneer AI cannot send commands to that shell. Typing needs command:execute, and what you type is recorded in the session transcript like any other input.
• Hand back makes the tab read-only again. Closing the tab, or 10 minutes without typing, also hands the shell back. The next time you message Pioneer AI, it is told that you typed in the shell, and reads it before it sends anything more.

Closing the Pioneer AI tab closes only your view of it: the shell keeps running on the endpoint. Pioneer AI leaves its shells open when it finishes, so you can look at the result or ask for more. A shell nobody uses closes after 10 minutes.

Let Pioneer AI run a command in your tab

Pioneer AI sees the terminal tabs you have open, up to 8, with each tab’s name, shell, and operating system. Ask it to run something in one of them, for example “run ipconfig /all in my PowerShell tab”. It types the command and Enter into that tab, as if you had typed it, and reads the output until the tab is quiet for 1.5 seconds, or for up to 60 seconds. The output it reads goes to your AI provider, like any tool result.

Whether the command asks first depends on what it does. See Shell commands. A High impact command in your tab always asks you, with a card such as Run in PowerShell on PC-1: Restart-Computer. The command runs only while that tab is open in the viewer.

Permissions

Permission	Name in the role editor	What it allows in the viewer
command:execute	Execute commands on endpoints	The Terminal button and every shell, as either account. Saving and clearing your own default layout. Startup commands.
terminal:layout:manage	Save and clear an endpoint’s default terminal layout, including the startup commands it runs	Save as endpoint default and Clear endpoint default. Owner and Support Manager hold it by default.
script:read	Read the script library	With command:execute, the Scripts menu.
script:run_unapproved	Run a script that has not been approved	Draft scripts in the Scripts menu.
endpoint:read	Read endpoints	Endpoint information, and its Overview, Hardware, and Network tabs.
software:read	Read the software catalog and installed inventory	The Software tab of Endpoint information.
patch:read	Read patch state and compliance	The Updates tab of Endpoint information.

Opening the viewer on an endpoint with remote desktop also needs remote:initiate and the permission for the session’s access mode. See Remote access and Permissions.

Verify

Open the terminal, and run whoami in a tab. It prints the tab’s account: nt authority\system or root for the agent’s account, or the user’s name for a tab as the signed-in user. The session appears under Commands > Console > Session transcripts on the endpoint.

If something goes wrong

Symptom	Cause	Fix
No Terminal button in the viewer	You lack command:execute.	Ask for a role that includes it.
A tab says This tab runs as the signed-in user, which is not available:	The signed-in user is not available. The rest of the line says why.	See Run as the agent or the signed-in user.
Startup commands not sent: in a tab	Script execution is off, you lack command:execute, or the tab is not part of a saved layout.	Read the reason on the same line. Save the layout before relying on its startup commands.
Save as endpoint default is missing	You lack terminal:layout:manage.	Save it as your own default, or ask someone who holds the permission.
A terminal session is refused by policy	remote_shell.enabled is off for the endpoint.	See Control terminal access.
A tab says This shell closed after 15 minutes without input.	A sign-in to resume an idle session is required for the endpoint, so idle shells close after the pause time.	Open a new tab. See Require a sign-in to resume.
dir /s fails in PowerShell	PowerShell’s dir does not take cmd switches.	Use a cmd tab, or cmd /c dir /s.

Next steps

• Start a remote desktop session
• Live metrics and the remote console
• Scripts