Remote Execution via SSH

Relevant source files

The following files were used as context for generating this wiki page:

• packages/coding-agent/DEVELOPMENT.md
• packages/coding-agent/test/acp-builtins.test.ts
• packages/coding-agent/test/tools/ssh-url-approval-gate.test.ts
• packages/coding-agent/src/prompts/system/system-prompt.md
• packages/coding-agent/src/prompts/agents/librarian.md

Remote Execution via SSH in the Oh My Pi coding harness allows agents to perform operations on remote filesystems and execute commands across network boundaries. This system extends the reach of built-in tools like read, write, and grep beyond the local environment by leveraging SSH as a transport layer. This capability is integrated into the core execution backend, enabling the agent to interact with remote repositories or servers as if they were local, provided the appropriate credentials and host configurations are in place.

The system is governed by strict security protocols, including an execution-tier approval gate. Operations targeting ssh:// URLs are classified as high-risk "exec" actions, requiring explicit user approval or a valid interactive UI session to proceed. This ensures that the agent cannot perform unauthorized remote mutations or data exfiltration without oversight.

Sources: packages/coding-agent/DEVELOPMENT.md:57, packages/coding-agent/test/tools/ssh-url-approval-gate.test.ts:16-20

Architecture and Components

The SSH execution system is structured around several key components that manage connections, command execution, and configuration.

Subsystem Overview

Component	Responsibility
SSH Executor	Handles the actual execution of commands on the remote host.
Connection Manager	Manages the lifecycle of SSH sessions and pooled connections.
Config Writer	Persists SSH host configurations (host, username, scope) to disk.
SSH Tool	The agent-facing tool that exposes SSH capabilities.
Approval Gate	Validates ssh:// targets and enforces "exec" tier security restrictions.

Sources: packages/coding-agent/DEVELOPMENT.md:120, packages/coding-agent/test/acp-builtins.test.ts:745-760, packages/coding-agent/test/tools/ssh-url-approval-gate.test.ts:18-20

Integration with Built-in Tools

Remote execution is not limited to a standalone ssh tool. Standard filesystem tools are enhanced to recognize ssh:// URIs. When a path like ssh://localhost/etc/hostname is provided to the read or write tool, the system routes the request through the SSH transport layer instead of the local filesystem API.

Security and Approval Gates

A critical feature of SSH execution is the ExtensionToolWrapper approval gate. This gate acts as a production-tier security layer that intercepts tool calls before they reach the execution engine.

Execution Tiering

The system classifies ssh:// targets as "exec-tier". This means even "read" operations on remote hosts are treated with the same severity as executing a binary locally. In environments without an interactive UI, these calls are automatically rejected to prevent unauthorized remote access.

• Read/Grep/Write: When targeted at an SSH URL, these tools transition from their standard tier (read or write) to the "exec" tier.
• Path Expansion: For tools like grep that take multiple paths, the gate performs a substring scan. If any path contains an ssh:// prefix, the entire operation requires high-tier approval.

Sources: packages/coding-agent/test/tools/ssh-url-approval-gate.test.ts:16-20, packages/coding-agent/test/tools/ssh-url-approval-gate.test.ts:68-80

Approval Sequence

Configuration and Management

Users and agents manage SSH hosts through built-in slash commands. These commands allow for listing, adding, and removing remote host definitions.

SSH Slash Commands

The /ssh command suite provides the interface for host management. Host configurations include the host address, username, and the configuration scope (e.g., user or project).

Command	Description	Parameters
/ssh list	Lists all configured SSH hosts.	N/A
/ssh add	Adds a new SSH host configuration.	--host, --user, --scope
/ssh remove	Removes a host configuration.	<name>

Sources: packages/coding-agent/test/acp-builtins.test.ts:717-730, packages/coding-agent/test/acp-builtins.test.ts:745-760

Configuration Persistence

When a host is added via /ssh add, the addSSHHost function persists the metadata. The configuration is stored in a JSON format within the .omp directory of the specified scope.

// Example of an SSH host configuration object
const hostConfig = {
    host: "remote-server.com",
    username: "dev-user",
    // auth details omitted for brevity
};

Sources: packages/coding-agent/test/acp-builtins.test.ts:748-765

Remote Research via Librarian Agent

The librarian agent utilizes SSH execution (among other tools) to research external libraries by reading remote source code. It follows a specific procedure to locate sources, prioritizing local node_modules before attempting to clone or access remote repositories via SSH or Git.

1. Locate Source: Checks local dependencies.
2. Clone/Access: If remote, uses tools to fetch content (often involving SSH-based Git operations).
3. Investigate: Uses grep, glob, and read (compatible with remote execution) to trace implementations.

Sources: packages/coding-agent/src/prompts/agents/librarian.md:73-95

Conclusion

Remote Execution via SSH provides a powerful extension to the Oh My Pi agent's capabilities, allowing it to operate across distributed environments. By integrating SSH transport directly into standard file tools and enforcing strict security gates, the system maintains a balance between high-utility remote access and robust security standards.