Docs › User › Terminal & Sandboxed Shell

🖥 Terminal & Sandboxed Shell

Run commands in a full interactive terminal or let the AI agent execute them safely in an isolated shell.

Overview

Oryn provides two complementary ways to run shell commands. The interactive terminal gives you a real PTY session — colour output, cursor movement, and interactive programs like vim or fzf all work as expected — powered by node-pty when running in the desktop app. Alongside that, the AI agent uses a sandboxed shell (shell-mcp) to execute commands on your behalf: it enforces workspace boundaries, blocks known-dangerous command patterns, applies a hard timeout, and is designed to run inside a Docker container with network access disabled for additional isolation. Together these two layers let you work freely in the terminal while keeping the agent's autonomous actions safe and auditable.

How it works

In the desktop app, the interactive terminal is backed by node-pty, which spawns a genuine pseudo-terminal process (PowerShell on Windows, your login shell on macOS/Linux) and relays data between the shell and the xterm.js renderer over Electron IPC. When node-pty is unavailable (for example in a headless or CI environment), the app automatically falls back to the .NET AgentTerminalsController, which starts a process with redirected stdout/stderr and streams output to the renderer via Server-Sent Events at 200 ms intervals, supporting stdin writes for interactive prompts. The agent's autonomous commands go through shell-mcp, an MCP server that checks every command against a list of banned patterns (recursive root deletion, fork bombs, destructive disk operations, pipe-to-shell fetches, and host power commands) before executing it, and refuses any working directory that resolves outside the workspace root. Sessions managed by shell-mcp keep a ring buffer of up to 1,000 output lines, while AgentTerminalsController buffers up to 5,000 lines and kills the entire process tree on timeout or explicit request.

What you can do

Real PTY terminalFull pseudo-terminal via node-pty: true colour (xterm-256color / truecolor), cursor control, and interactive programs like vim, fzf, and progress bars work correctly.

Automatic shell detectionOn Windows Oryn picks PowerShell (preferring pwsh if COMSPEC points to it); on macOS/Linux it uses your $SHELL login shell, falling back to /bin/bash.

Terminal resizeThe PTY session tracks the renderer window size and resizes the underlying shell process when you resize the panel, keeping line wrapping correct.

Sandboxed agent shellThe AI agent runs commands through shell-mcp, which enforces workspace confinement, banned-pattern blocking, and a configurable timeout (max 60 seconds per shell_run call).

Banned-pattern safety filtershell-mcp and AgentTerminalsController both block commands matching known-destructive patterns before execution, including recursive root deletion, fork bombs, disk format commands, and pipe-to-shell download patterns.

Dangerous-command approval gateAgentTerminalsController requires explicit approval (Approved: true) before running commands such as rm -rf, git reset --hard, kubectl delete, terraform destroy, and docker system prune.

Live output streamingAgent terminal sessions stream new output lines to the renderer via Server-Sent Events; each line carries a sequence number so the client can resume after a reconnect without missing output.

Stdin passthroughInteractive prompts (npm init, apt install, and similar) receive keystrokes or paste blobs sent by the renderer to the running process's stdin.

Per-agent step terminalsEach orchestration step (Coder, Tester, Deployer) can open its own named terminal session, making it easy to follow what each agent step is doing independently.

Persistent ring bufferTerminal output is kept in a capped ring buffer (1,000 lines in shell-mcp, 5,000 in AgentTerminalsController) so you can scroll back through recent output without the process being alive.

Process-tree killKilling a session terminates the entire process tree, not just the top-level shell, preventing orphaned background processes.

Idle and step timeoutAgentTerminalsController automatically kills sessions that exceed their timeout (1–240 minutes, default 30) and appends a timeout notice to the output buffer.

HTTP API fallbackWhen node-pty native binaries are not available (headless CI, systems without build toolchain), Oryn falls back to the .NET process-based terminal API transparently.

How to use it

Open the terminal panel
Click the Terminal tab in the bottom panel or press the keyboard shortcut shown in the status bar. If node-pty is available, a PTY session starts immediately using your default shell (PowerShell on Windows, your login shell elsewhere).
Type commands interactively
Use the terminal exactly as you would any system terminal. Colour output, cursor-based programs (vim, less, htop), and interactive prompts all behave correctly in the PTY-backed session.
Resize as needed
Drag the panel divider to resize the terminal pane. The PTY process automatically receives the new column and row dimensions so line wrapping stays accurate.
Let the agent run commands
When you ask the AI agent to build, test, or install dependencies, it executes commands through the sandboxed shell-mcp layer. You will see a dedicated terminal panel for the relevant agent step (for example, 'Tester') showing live streaming output.
Review and approve dangerous commands
If the agent (or a workflow) requests a command that matches the dangerous-command list (such as git reset --hard or terraform destroy), Oryn pauses and prompts you to approve before proceeding. Read the command carefully and confirm only if intended.
Send input to interactive prompts
If a running process asks a question (for example, a yes/no prompt during npm init), type your response in the terminal panel. Keystrokes are sent to the process's stdin in real time.
Kill a session
Click the kill button in the terminal panel header, or use the agent step controls, to terminate the process and its entire child tree immediately.

Example

You ask the agent: "Install the project dependencies and run the test suite." The agent opens two terminal sessions — one labelled 'Installer' and one labelled 'Tester'. In the Installer session it calls shell_run with the command npm ci; you see live output scroll by as packages are fetched. Because the workspace root is set, any attempt by the command to write outside the project directory is refused automatically. Once npm ci exits with code 0, the Tester session opens and runs npm test, streaming each test result line via SSE. When the suite finishes, both sessions display their exit codes and the agent reports the overall result back in the chat.

Admin notes

The shell-mcp server reads the workspace root from the ORYN_WORKSPACE_ROOT environment variable. If this variable is not set, it defaults to the process working directory, which means workspace-boundary enforcement is effectively disabled — set this variable explicitly in production deployments. For full isolation the shell-mcp server is designed to run inside a Docker container with --network=none; this must be configured at the infrastructure level (Oryn does not start Docker automatically). AgentTerminalsController resolves the workspace root by walking up the directory tree looking for an Oryn.sln file; on installations where the solution file is not present, it falls back to Environment.CurrentDirectory. Session timeouts for agent terminals can be set per-request between 1 and 240 minutes (default 30); plan accordingly for long-running build or migration tasks. The node-pty native module requires Python and MSBuild (Windows) or node-gyp (Linux/macOS) at install time; CI environments that skip native builds will use the HTTP API fallback automatically.