pi-open-terminal

A pi extension that integrates with Open Terminal to enable remote command execution. This allows you to run pi commands from remote connections via HTTP API.

Features

• 🌐 Remote API Access: Execute commands remotely via Open Terminal's REST API
• 🔐 Secure: Configurable API key authentication
• ⚙️ Configurable: Custom port, host, and API key settings
• 🚀 Auto-start: Optional boot-time startup (Windows, macOS, Linux)
• 🔧 Bare Metal: Runs directly on your system without Docker
• 📡 Status Monitoring: Real-time server status in pi's status bar

Requirements

• Node.js 18+
• Python 3.8+ (for Open Terminal)
• uv or pip for installing Open Terminal
• tmux (for some Open Terminal features)

Installation

The extension will be automatically loaded by pi when placed in ~/.pi/agent/extensions/.

Open Terminal will be automatically installed via uvx on first use (preferred) or pip as fallback.

Commands

| Command | Description | |---------|-------------| | /open-terminal-start | Start the Open Terminal server | | /open-terminal-stop | Stop the Open Terminal server | | /open-terminal-restart | Restart the Open Terminal server | | /open-terminal-status | Show current server status | | /open-terminal-config | Configure settings (port, API key, etc.) | | /open-terminal-key | Show or regenerate API key | | /open-terminal-setup | Setup auto-start on boot | | /open-terminal-remove | Remove auto-start configuration |

Configuration

View Current Configuration

/open-terminal-config

Change Port

/open-terminal-config port 9000

Change API Key

/open-terminal-config api-key my-secret-key

Enable/Disable Auto-start

/open-terminal-config auto-start true
/open-terminal-config auto-start false

Regenerate API Key

/open-terminal-key regenerate

API Usage

Once the server is running, you can execute commands remotely:

# Execute a command
curl -X POST http://localhost:8080/api/execute \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "ls -la", "cwd": "/path/to/dir"}'

# Check command status
curl http://localhost:8080/api/execute/COMMAND_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

# List files
curl "http://localhost:8080/api/files?path=/path/to/dir" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Read a file
curl http://localhost:8080/api/files/content?path=/path/to/file \
  -H "Authorization: Bearer YOUR_API_KEY"

Auto-start on Boot

macOS

Uses launchd (LaunchAgents). Creates ~/Library/LaunchAgents/com.pi.openterminal.plist.

/open-terminal-setup

To remove:

/open-terminal-remove

Linux

Uses systemd user services. Creates ~/.config/systemd/user/pi-open-terminal.service.

/open-terminal-setup

To remove:

/open-terminal-remove

Windows

Creates a batch file in the Startup folder.

/open-terminal-setup

To remove:

/open-terminal-remove

Default Configuration

On first run, a configuration file is created at:

• macOS/Linux: ~/.config/pi-open-terminal/config.json
• Windows: %USERPROFILE%\.config\pi-open-terminal\config.json

Default values:

{
  "port": 8080,
  "host": "0.0.0.0",
  "apiKey": "pi_<random-32-chars>",
  "autoStart": false,
  "enableTerminal": true,
  "corsOrigins": "*"
}

Integration with pi

The extension provides tools for programmatic control:

• open_terminal_execute - Execute commands via the API
• open_terminal_status - Get server status

These tools can be used by pi itself or other extensions to interact with the Open Terminal server.

Troubleshooting

Server won't start

1. Check if port is already in use: lsof -i :8080 (macOS/Linux) or netstat -ano | findstr 8080 (Windows)
2. Try a different port: /open-terminal-config port 9000
3. Check logs in ~/.config/pi-open-terminal/logs/

Open Terminal not found

The extension will attempt to install Open Terminal automatically. If it fails, install manually:

# Using uv (recommended)
uv tool install open-terminal

# Or using pip
pip install open-terminal

Auto-start not working

• macOS: Check launchctl list | grep com.pi.openterminal
• Linux: Check systemctl --user status pi-open-terminal
• Windows: Check if the .bat file exists in %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup

Security Considerations

⚠️ Warning: Open Terminal runs commands directly on your system. Only use this in trusted environments.

• Always use a strong, unique API key
• Consider using a firewall to restrict access to the port
• Don't expose the server to the public internet without additional security measures (reverse proxy, VPN, etc.)
• The API key is stored in ~/.config/pi-open-terminal/config.json - protect this file

License

MIT