remote-bridge-cli

RemoteBridge 🌉

Turn remote-server work into safe, token-efficient MCP tools instead of making your AI improvise SSH every time.

RemoteBridge is a Rust CLI and MCP server for AI-assisted remote workflows. It syncs local code with rsync, runs remote commands over SSH, gathers logs and diagnostics, compares environments, and wraps all of that in a config-aware tool surface your AI can use directly.

It does not replace SSH as a protocol. It makes SSH more useful for AI agents.

What Problem This Actually Solves

If you let an AI talk to a server through raw ssh, it can usually get the job done. But it has to rediscover the same facts over and over:

• Which host should I use?
• What directory is the app deployed in?
• How do I restart this service?
• Where are the logs?
• Which commands are safe here?
• How much output can I afford to send back without blowing context?

That repeated discovery is where time, tokens, and mistakes accumulate.

RemoteBridge moves those recurring facts and workflows into tools. Instead of:

ssh user@host "cd /var/www/app && npm install && pm2 restart app && tail -n 100 /var/www/app/logs/error.log"

your AI can call:

• sync_to_remote
• deploy
• fetch_logs
• diagnose_failure
• compare_targets

That is the difference between "AI with shell access" and "AI with an operational interface."

Direct SSH vs RemoteBridge MCP

Use direct SSH when:

• You want a fully interactive shell.
• You already know the exact command.
• You need ad hoc exploration and do not care about token cost.
• You are doing a one-off urgent command and want raw terminal behavior.

Use RemoteBridge when:

• The AI is driving the workflow.
• The same server facts keep getting rediscovered.
• You want deploy/restart/log/debug flows to be repeatable.
• You need guardrails around destructive commands.
• You want compact answers instead of full shell transcripts.
• You want config-aware operations like "compare staging and production" instead of open-ended shell probing.

Direct SSH can be faster for one command. RemoteBridge is usually better for the full AI loop.

Why This Saves Tokens In Practice

RemoteBridge is useful when it removes low-value conversation between the model and the server.

It saves tokens in a few concrete ways:

• run_remote_command truncates combined stdout and stderr to a shared line budget, so the model gets the important tail instead of a full transcript.
• preflight_check gathers OS and runtime facts in one remote call instead of making the AI issue several separate shell commands.
• fetch_logs pulls configured log files in one structured response instead of the AI repeatedly asking where logs live and tailing each file manually.
• diagnose_failure gathers service state, listeners, disk, memory, runtime info, and recent logs in one pass, then summarizes likely causes.
• compare_targets turns "SSH into staging, SSH into prod, inspect both, diff mentally" into one semantic tool call.
• deploy and restart_service remove the need for the AI to restate shell glue like cd /path && ... every time.
• Config values such as remote_path, restart_cmd, logs, allowed_commands, and blocked_patterns are stored once and reused on every call.

The important point is not just "fewer SSH commands." It is "less repeated reasoning around the same infrastructure facts."

Why This Is Better Than Letting AI Freestyle Shell

Raw SSH gives the AI a lot of power, but very little structure.

RemoteBridge adds:

• Config awareness: target host, deploy path, restart command, and log paths live in remotebridge.yaml.
• Operational semantics: tools like deploy, diagnose_failure, and compare_targets describe intent, not just shell syntax.
• Safer defaults: dangerous commands can require confirmation, be blocked entirely, or be limited to allowlisted prefixes.
• Better output discipline: the MCP surface returns compressed, useful output instead of dumping everything.
• Local + remote coordination: syncing local files to a remote server is part of the same workflow instead of a separate manual step.

That last point matters. A remote shell alone cannot see your local uncommitted code. RemoteBridge can sync exactly what the AI changed locally, then execute the remote step that depends on it.

Core Value

RemoteBridge is not trying to beat SSH at being a shell.

It is trying to give AI agents a better abstraction than:

• guess the host
• guess the path
• guess the service manager
• guess the logs
• dump too much output
• try again

Features

Feature	Why it matters
Rsync Sync	Push local code to the server without re-uploading everything
SSH Multiplexing	Reuses OpenSSH control connections across repeated sync and command calls
Structured MCP Tools	Lets the AI call semantic actions instead of building shell strings each time
Output Truncation	Keeps command responses small enough to stay useful in model context
Preflight Check	Captures runtime facts in one step
Deploy Pipeline	Encodes sync → restart → failure-log flow as one operation
Failure Diagnosis	Pulls service state, runtime facts, listeners, disk, memory, and logs into one compact summary
Target Comparison	Surfaces config drift and runtime drift between environments
Safety Gates	Confirmation, hard blocks, and allowlists reduce destructive mistakes
Audit Log	Records what actually ran and how it exited
Watch Mode	Keeps a remote target in sync during an edit/test loop
Per-target SSH Config	Supports host/user/path/port/key per environment

A Practical Example

Without RemoteBridge, an AI debugging a broken deploy often does something like this:

• SSH in.
• Ask for pwd.
• Ask for ls.
• Try to find the app path.
• Guess how to restart the service.
• Ask for logs.
• Pull too much output.
• Ask follow-up questions because the output was noisy.

With RemoteBridge, the same request can be:

You: "The staging deploy is broken. Diagnose it."

The AI can call diagnose_failure and get back:

• target identity
• inferred service manager
• service health
• runtime versions
• disk or memory pressure signals
• relevant log excerpts
• likely causes
• next-step suggestions

That is a much better use of context than a multi-turn shell transcript.

Quick Start

1. Install

Prerequisites: Rust, rsync, and ssh available in PATH.

npm install -g remote-bridge-cli

2. Add the MCP server to your AI tool

claude mcp add remote-bridge --scope user -- remote-bridge mcp

See MCP Support below for other tools.

3. Initialize project config

remote-bridge init --name my-app -H your-server.com --user ubuntu --path /var/www/app

That creates remotebridge.yaml, which becomes the shared source of truth for your AI workflows.

Example Configuration

project_name: "my-app"
targets:
  staging:
    host: "13.234.xx.xx"
    user: "ubuntu"
    remote_path: "/var/www/html/app"
    port: 22
    ssh_key: "~/.ssh/id_rsa"
    restart_cmd: "pm2 restart app"
    logs:
      - "/var/www/html/app/logs/error.log"
      - "/var/log/nginx/error.log"
    require_confirmation: false
    exclude:
      - "node_modules/"
      - "*.log"
    blocked_patterns:
      - "rm -rf"
      - "drop table"
    allowed_commands:
      - "npm"
      - "pm2"
    audit_log: "~/.remote-bridge-staging.log"
  production:
    host: "prod.example.com"
    user: "ubuntu"
    remote_path: "/opt/app"
    ssh_key: "~/keys/prod.pem"
    restart_cmd: "systemctl restart myapp"
    logs:
      - "/opt/app/logs/error.log"
    require_confirmation: true

Why remotebridge.yaml Matters

This file is the reason the MCP tool is more useful than raw SSH.

It stores facts the AI should not have to rediscover:

• where the app lives
• how it restarts
• which logs matter
• which commands are safe
• which environment needs stronger confirmation

Once that information is encoded once, every future tool call gets simpler and cheaper.

CLI Commands

Command	Description
init	Create a new remotebridge.yaml
sync	Sync local files to the remote server
sync --dry-run	Preview rsync changes without touching the server
run <cmd>	Execute one remote command
preflight	Collect remote OS and runtime versions
logs	Fetch recent configured logs
logs --follow	Stream configured logs live
restart	Restart the configured service
deploy	Sync, restart, and fetch failure context if restart fails
watch	Poll local files and auto-sync on change
apply	Parse Markdown from AI output and apply file changes plus shell commands

Integrating With AI CLIs

RemoteBridge is also pipe-friendly.

Claude Code

claude "Fix the database connection in src/db.ts and restart the app" --non-interactive \
  | remote-bridge apply --target staging

Gemini CLI

gemini "Add rate limiting to the Express API" \
  | remote-bridge apply --target staging

Aider

aider --message "Refactor the login logic" --apply \
  | remote-bridge apply --target staging

MCP Support

RemoteBridge is a native MCP server. Any MCP-compatible AI IDE can use it.

Available MCP Tools

Tool	Practical value
sync_to_remote	Push local code to the server from the same AI session
run_remote_command	Run remote shell commands with bounded output
preflight_check	Get runtime facts in one compact response
fetch_logs	Pull configured logs without rediscovering paths
restart_service	Reuse the configured restart command safely
deploy	Run the standard remote deploy flow as one action
diagnose_failure	Collect and summarize failure context instead of streaming raw shell debugging
compare_targets	Compare environments using both config and live runtime facts

What These Tools Let AI Do Better Than Raw SSH

diagnose_failure is the clearest example.

A raw SSH agent has to decide:

• which service manager exists
• how to inspect it
• which logs to read
• how many lines to tail
• whether disk, memory, or port state might be relevant
• which lines are likely signal versus noise

diagnose_failure bakes that investigation into one operation.

compare_targets is another example. SSH can inspect one server at a time. This tool compares:

• host/path/config differences
• confirmation-policy drift
• service-manager differences
• runtime version differences
• high-level compatibility risks

That is not impossible with SSH. It is just expensive and repetitive for AI.

Example Requests

Inside an MCP-enabled IDE, you can say:

• "Sync my current project to staging."
• "Deploy the latest local changes to staging."
• "Check what runtimes are installed on production."
• "The app failed after deploy. Diagnose staging."
• "Compare staging and production and tell me if runtime drift could explain the bug."
• "Show me the last 100 log lines for production."

MCP Configuration Examples

Claude Desktop

File: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "remote-bridge": {
      "command": "remote-bridge",
      "args": ["mcp"]
    }
  }
}

Cursor

File: ~/.cursor/mcp.json or .cursor/mcp.json

{
  "mcpServers": {
    "remote-bridge": {
      "command": "remote-bridge",
      "args": ["mcp"]
    }
  }
}

VS Code / Cline / Continue / Copilot-compatible MCP clients

{
  "servers": {
    "remote-bridge": {
      "type": "stdio",
      "command": "remote-bridge",
      "args": ["mcp"]
    }
  }
}

Codex CLI

File: ~/.codex/config.json

{
  "mcpServers": {
    "remote-bridge": {
      "command": "remote-bridge",
      "args": ["mcp"]
    }
  }
}

Or inline:

codex --mcp-server "remote-bridge mcp" "Diagnose the staging deploy failure"

Generic MCP Pattern

{
  "command": "remote-bridge",
  "args": ["mcp"],
  "transport": "stdio"
}

SSH Authentication

RemoteBridge uses your existing SSH setup.

• Copy your key to the server:

  ssh-copy-id -i ~/.ssh/id_rsa.pub [e-mail]
  

• Or specify key and port in config:

  targets:
    staging:
      host: "13.234.xx.xx"
      user: "ubuntu"
      port: 2222
      ssh_key: "~/keys/staging.pem"
  

• Or use ~/.ssh/config aliases:

  Host staging-server
      HostName 13.234.xx.xx
      User ubuntu
      IdentityFile ~/keys/my-key.pem
      Port 22
  

  Then point host at the alias:

  targets:
    staging:
      host: "staging-server"
      user: "ubuntu"
  

Safety Model

RemoteBridge is designed for AI-driven execution, so safety is not optional.

Confirmation Gate

Commands containing risky patterns such as sudo, rm, drop, delete, shutdown, reboot, killall, curl | bash, and similar destructive sequences require confirmation before execution.

Hard Block

Anything in blocked_patterns is always rejected:

targets:
  production:
    blocked_patterns:
      - "rm -rf"
      - "drop table"
      - "truncate"

Allowlist

If allowed_commands is set, only matching prefixes are allowed:

targets:
  production:
    allowed_commands:
      - "npm"
      - "pm2"
      - "systemctl restart myapp"

Audit Log

Every command is logged automatically:

[1742660591] host=your-server.com path=/var/www/app exit=0 cmd=npm install
[1742660612] host=your-server.com path=/var/www/app exit=-2 cmd=rm -rf /var/data

Exit codes:

• 0+ actual process exit code
• -1 skipped by user
• -2 hard blocked
• -3 not allowlisted

Other Protections

• require_confirmation: true can force confirmation on every command for sensitive targets.
• sync --dry-run previews what will change before syncing.
• No passwords are stored by RemoteBridge.
• No secrets need to live in remotebridge.yaml.
• MCP output stays bounded so one noisy command does not flood model context.

Honest Tradeoff

If you want a raw terminal, use SSH.

If you want an AI to reliably work with remote infrastructure without repeatedly wasting tokens on rediscovery, shell glue, and noisy output, use RemoteBridge.

That is the value proposition.

Contributing

Contributions and issues are welcome at GitHub Issues.

License

MIT License.