Terminal Commands

Desktop can run terminal commands as part of an agent session. Commands are requested by the AI, routed through the Gateway, approved by the user when required, and executed by the native Desktop runtime inside the selected workspace.

Command Flow#

When the agent needs the terminal, the flow is:

1. The agent requests a command tool such as run_command, run_terminal_command, or execute_command.
2. The Gateway creates or reuses an approval session.
3. Desktop receives the tool_call_request.
4. If approval is required, Desktop shows the command, working directory, and timeout.
5. After approval, the Tauri host executes the command locally.
6. stdout and stderr stream into Desktop as live chunks.
7. The final result returns to the Gateway and conversation timeline.

Command Arguments#

Desktop accepts the common command tool shape:

{
  "command": "pnpm test -- --runInBand",
  "cwd": "apps/website",
  "timeoutMs": 120000
}

Supported aliases:

| Field | Aliases | Meaning | | ----- | ------- | ------- | | command | cmd, script | Shell command to run | | cwd | workingDir, working_dir | Working directory relative to the selected workspace | | timeoutMs | timeout, timeout_ms | Command timeout in milliseconds |

Shell Behavior#

Desktop runs commands through the platform shell:

| Platform | Shell | | -------- | ----- | | macOS / Linux | /bin/sh -c | | Windows | cmd /C |

The command runs with the selected workspace as its root by default. If cwd is provided, it must resolve to an existing directory inside the workspace.

Output Streaming#

Desktop streams stdout and stderr while the command is running. The final tool result also includes buffered output:

{
  "exitCode": 0,
  "stdout": "Test Files  4 passed\\n",
  "stderr": "",
  "stdoutTruncated": false,
  "stderrTruncated": false,
  "timedOut": false,
  "cancelled": false,
  "durationMs": 1842
}

Each stream is capped to protect the UI from very large logs. If output is truncated, the final result sets stdoutTruncated or stderrTruncated to true.

Timeouts and Cancellation#

Desktop uses a conservative default timeout:

| Setting | Value | | ------- | ----- | | Default timeout | 30 seconds | | Minimum timeout | 100 ms | | Maximum timeout | 10 minutes | | Output cap | 1 MiB per stream |

Long-running commands should request an explicit timeout:

{
  "command": "pnpm build",
  "timeoutMs": 300000
}

Commands can be cancelled from Desktop while they are running. Cancelled commands return cancelled: true.

Environment Handling#

Before running a command, Desktop removes environment variables whose names look sensitive, including keys that contain markers such as TOKEN, SECRET, PASSWORD, PRIVATE_KEY, ACCESS_KEY, API_KEY, AUTH, CREDENTIAL, SESSION, or COOKIE.

Desktop also sets:

MIRABRIDGE_TOOL_EXECUTOR=desktop
MIRABRIDGE_ENV_SCRUBBED=1

This makes command logs easier to identify and confirms that the command went through the Desktop executor path.

Denied Commands#

Desktop refuses commands that match known destructive patterns, even if a user clicks approve. Examples include broad deletion commands, destructive git resets, disk formatting commands, forced permission changes, and shutdown/reboot calls.

If a command is denied, the tool result returns an error such as:

command denied on desktop: contains 'git reset --hard'

Good Command Patterns#

Prefer focused, inspectable commands:

pnpm --filter @miratech/website test
pnpm --filter @miratech/website typecheck
git status --short
git diff -- apps/website/src/content/docs

Avoid commands that depend on interactive prompts unless the project already supports non-interactive flags:

pnpm install --frozen-lockfile
npm test -- --watch=false

Mobile Visibility#

When mobile is connected to the same account and session, it can show terminal status, approval requests, and command output routed through the Gateway. The command still executes on Desktop; mobile is the remote control and monitoring surface.

Next Steps#

• Approvals & Security - review the safety model
• Remote Session Management - monitor sessions from mobile