Documentation/Everyday use
Use the remote terminal
Run commands on the target device and distinguish workspace access from the operating system identity.
On this page
Connect a terminal
Open the target from Devices, select Terminal and connect. Check the device name and operating system, then wait for the remote prompt. You need terminal permission and a target that supports it.
Commands execute on the remote device in the connection's system account context. This is not your local terminal, and its operating system account is not necessarily the same as your workspace user.
Check the environment first
Start with read-only commands to confirm your location and identity. On Linux / macOS:
pwd
whoami
In Windows Command Prompt:
cd
whoami
Read the output before continuing. Paths, available commands and permissions depend on the remote system and shell. Do not apply commands from one operating system to another without checking.
Run commands and verify results
Send a focused group of commands, wait for output, and check errors and the final result. Before deleting files, stopping services or restarting a system, confirm the target, impact and any needed backup; these actions can interrupt your connection.
For transfers, use the file page instead of pasting large binary or encoded payloads into a terminal. Keep workspace keys out of scripts, shell history and logs.
Disconnect and reconnect
Close the terminal session when finished. A lost connection does not guarantee the remote process stopped. After reconnecting, check the outcome before retrying, especially for commands that change data.
When AI uses a terminal, specify the device, allowed directories and task boundaries. External clients need terminal.open permission; see MCP setup.
Include the issue and the steps you took so it is easier to investigate.