@neoline/hostbridge 1.4.0 → 1.4.1

package/README.md

@@ -85,7 +85,43 @@ file_upload(session_id, "/absolute/local/script.py", "/remote/work/script.py")
 file_download(session_id, "/remote/work/result.log", "/absolute/local/result.log")
 ```
 
-Give file tools local and remote paths; do not paste base64 into tool arguments. Files larger than 100MiB are deliberately rejected with guidance to use remote pull instead, for example `curl`, `wget`, `git clone`, `modelscope download`, or another remote-native downloader. HostBridge does not plan a standard SSH/SFTP fast path; the reliable fallback for non-standard login flows is shell/base64, and large model/data movement should happen from the remote host.
+Give file tools local and remote paths; do not paste base64 into tool arguments. Files larger than 100MiB are deliberately rejected with guidance to use remote pull instead, for example `curl`, `wget`, `git clone`, `modelscope download`, or another remote-native downloader. The MCP file tools intentionally keep this shell/base64 backend for non-standard login flows. The optional `mock-ssh` bridge below exposes SFTP/SCP protocol compatibility on top of the same backend for clients which require SSH file-transfer channels.
+
+## Mock SSH bridge
+
+Some clients, including compute providers, know how to connect to SSH targets but cannot run HostBridge's MCP connector inside their local sandbox. `hostbridge mock-ssh` exposes one configured HostBridge host as a local SSH server while keeping the actual remote access path behind HostBridge. This is useful when the client-side SSH implementation runs outside a restricted sandbox.
+
+```bash
+hostbridge mock-ssh a800_95
+```
+
+By default HostBridge selects a free local port from `2222-2299`, creates host/client keys under `~/.hostbridge/mock-ssh/<host_id>/`, and writes a managed `Host hostbridge-<host_id>` block into `~/.ssh/config`. The command prints the chosen alias, port, config path, and identity file:
+
+```text
+hostbridge mock-ssh forwarding host 'a800_95'
+listening on ssh://127.0.0.1:2222
+ssh host alias: hostbridge-a800_95
+ssh config: /Users/alice/.ssh/config
+identity file: /Users/alice/.hostbridge/mock-ssh/a800_95/client_ed25519_key
+```
+
+Point the compute provider at the printed SSH alias, for example `ssh:hostbridge-a800_95`. To remove the managed SSH config block later:
+
+```bash
+hostbridge mock-ssh a800_95 --remove
+```
+
+Advanced options are still available for fixed deployments: `--listen-host`, `--port`, `--key-dir`, `--ssh-host-alias`, `--ssh-config`, and `--no-ssh-config`.
+
+The bridge supports:
+
+- SSH exec requests, suitable for compute `call_command` APIs.
+- Interactive shell channels.
+- SFTP upload/download/list/stat/mkdir/remove/rename operations.
+- OpenSSH `scp` in its default SFTP-backed mode.
+- Legacy OpenSSH `scp -O` mode through AsyncSSH's SCP server.
+
+Each SSH channel opens its own HostBridge backend session and closes it when the channel ends, so an interactive shell `exit` does not kill later exec or file-transfer requests. The SFTP/SCP implementation is a compatibility layer backed by HostBridge's shell/base64 transfer primitives, so it keeps working across JumpServer/menu/wrapper login flows where direct remote SFTP is unavailable. It inherits the same transfer size limit (100MiB by default); for larger files, start a remote-native pull from the target host.
 
 ## Daemon lifecycle
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neoline/hostbridge",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "HostBridge MCP server for persistent allowlisted SSH and shell sessions.",
   "type": "module",
   "license": "MIT",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hostbridge"
-version = "1.4.0"
+version = "1.4.1"
 description = "HostBridge MCP server for persistent allowlisted SSH and shell sessions."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -39,6 +39,7 @@ dependencies = [
   "mcp>=1.0.0",
   "pexpect>=4.9.0",
   "cryptography>=42.0.0",
+  "asyncssh>=2.14.0",
 ]
 
 [project.optional-dependencies]

package/src/server_control_mcp/__init__.py

@@ -8,7 +8,7 @@ import subprocess
 from typing import NoReturn
 
 __all__ = ["__version__", "ensure_runtime"]
-__version__ = "1.4.0"
+__version__ = "1.4.1"
 
 # (import_name, pip_name) pairs for runtime dependency probing.
 _REQUIRED_DEPENDENCIES = (

package/src/server_control_mcp/cli.py

@@ -54,7 +54,7 @@ SUPPORTED_INSTALL_TARGETS = (
     "antigravity",
     "kiro",
 )
-SETUP_COMMANDS = {"install", "setup", "check", "list", "remove", "reload", "secret", "step", "daemon"}
+SETUP_COMMANDS = {"install", "setup", "check", "list", "remove", "reload", "secret", "step", "daemon", "mock-ssh"}
 AskFunc = Callable[[str], str]
 SecretAskFunc = Callable[[str], str]
 VerifyFunc = Callable[[dict[str, object], int], "VerificationResult"]
@@ -1163,6 +1163,19 @@ def main(argv: list[str] | None = None) -> int:
     daemon_status = daemon_subparsers.add_parser("status", help="Show daemon status")
     daemon_status.add_argument("--socket", dest="socket_file", default=None, help="Unix socket path; default comes from HOSTBRIDGE_DAEMON_SOCKET or HOSTBRIDGE_DAEMON_DIR")
 
+    mock_ssh_parser = subparsers.add_parser("mock-ssh", parents=[config_parent], help="Expose a HostBridge host as a local SSH server")
+    mock_ssh_parser.add_argument("host_id")
+    mock_ssh_parser.add_argument("--listen-host", default="127.0.0.1")
+    mock_ssh_parser.add_argument("--port", type=int, default=None, help="Local SSH port; default auto-selects a free port from 2222-2299")
+    mock_ssh_parser.add_argument("--key-dir", help="Directory for generated mock SSH host/client keys")
+    mock_ssh_parser.add_argument("--ssh-host-alias", help="Host alias to manage in ~/.ssh/config; default hostbridge-<host_id>")
+    mock_ssh_parser.add_argument("--ssh-config", help="SSH config path; default ~/.ssh/config")
+    mock_ssh_parser.add_argument("--no-ssh-config", action="store_true", help="Do not write a managed Host block to SSH config")
+    mock_ssh_parser.add_argument("--remove", action="store_true", help="Remove the managed SSH config block and exit")
+    mock_ssh_parser.add_argument("--connect-timeout", type=int, default=60)
+    mock_ssh_parser.add_argument("--command-timeout", type=int, default=DEFAULT_VERIFY_TIMEOUT)
+    mock_ssh_parser.add_argument("--output-limit", type=int, default=120000)
+
     remove_parser = subparsers.add_parser("remove", parents=[config_parent], help="Remove a configured host")
     remove_parser.add_argument("host_id")
 
@@ -1217,6 +1230,30 @@ def main(argv: list[str] | None = None) -> int:
             foreground=getattr(args, "foreground", False),
             socket_file=getattr(args, "socket_file", None),
         )
+    if args.command == "mock-ssh":
+        from .mock_ssh import run_mock_ssh, uninstall_mock_ssh
+
+        ssh_config_path = Path(args.ssh_config).expanduser() if args.ssh_config else None
+        if args.remove:
+            return uninstall_mock_ssh(
+                args.host_id,
+                ssh_host_alias=args.ssh_host_alias,
+                ssh_config_path=ssh_config_path,
+            )
+
+        return run_mock_ssh(
+            host_id=args.host_id,
+            config_path=config_path,
+            listen_host=args.listen_host,
+            port=args.port,
+            key_dir=Path(args.key_dir).expanduser() if args.key_dir else None,
+            ssh_host_alias=args.ssh_host_alias,
+            ssh_config_path=ssh_config_path,
+            install_ssh_config=not args.no_ssh_config,
+            connect_timeout=args.connect_timeout,
+            command_timeout=args.command_timeout,
+            output_limit=args.output_limit,
+        )
     if args.command == "secret" and args.secret_command == "set":
         value = getpass.getpass(f"Secret value for {args.host_id}/{args.name}: ")
         set_host_secret(config_path, args.host_id, args.name, value)

package/src/server_control_mcp/daemon.py

@@ -267,8 +267,8 @@ def _max_sessions_per_host_from_env() -> int:
     return 0
 
 
-def build_manager() -> SessionManager:
-    registry = HostRegistry(load_hosts())
+def build_manager(config_path: Path | str | None = None) -> SessionManager:
+    registry = HostRegistry(load_hosts(config_path))
     policy = load_policy()
     manager = SessionManager(
         registry,

package/src/server_control_mcp/manager.py

@@ -117,10 +117,15 @@ def _tail(value: str, limit: int = MAX_OUTPUT_CHARS) -> str:
 
 
 def _extract_between_markers(raw: str, start_marker: str) -> str:
+    raw = raw.replace("\x1b[?2004h", "").replace("\x1b[?2004l", "")
     if start_marker in raw:
         raw = raw.split(start_marker, 1)[1]
     lines = raw.replace("\r\n", "\n").replace("\r", "\n").split("\n")
-    cleaned = [line for line in lines if not line.startswith("printf '") and "__SCM_EXIT_" not in line]
+    cleaned = [
+        line
+        for line in lines
+        if not line.startswith("printf '") and "__SCM_START_" not in line and "__SCM_EXIT_" not in line
+    ]
     return "\n".join(cleaned).strip("\n")
 
 
@@ -536,6 +541,44 @@ class SessionManager:
         result["content"] = data.decode("utf-8")
         return result
 
+    def file_write_bytes(
+        self,
+        session_id: str,
+        remote_path: str,
+        data: bytes,
+        *,
+        mode: str = "0644",
+        max_bytes: int = DEFAULT_MAX_TRANSFER_BYTES,
+        token_factory: TokenFactory = _new_token,
+        owner_agent_id: str | None = None,
+    ) -> dict[str, object]:
+        return self._upload_bytes(
+            session_id,
+            data,
+            remote_path,
+            mode=mode,
+            max_bytes=max_bytes,
+            token_factory=token_factory,
+            owner_agent_id=owner_agent_id,
+        )
+
+    def file_read_bytes(
+        self,
+        session_id: str,
+        remote_path: str,
+        *,
+        max_bytes: int = DEFAULT_MAX_TRANSFER_BYTES,
+        token_factory: TokenFactory = _new_token,
+        owner_agent_id: str | None = None,
+    ) -> dict[str, object]:
+        return self._download_bytes(
+            session_id,
+            remote_path,
+            max_bytes=max_bytes,
+            token_factory=token_factory,
+            owner_agent_id=owner_agent_id,
+        )
+
     def file_upload(
         self,
         session_id: str,
@@ -635,7 +678,7 @@ class SessionManager:
             finalize_script = (
                 "set -e; "
                 f"target={remote_q}; mode={mode_q}; tmp_b64={shlex.quote(tmp_b64)}; tmp_out={shlex.quote(tmp_out)}; "
-                'base64 -d "$tmp_b64" > "$tmp_out"; '
+                '{ base64 -d < "$tmp_b64" 2>/dev/null || base64 -D < "$tmp_b64"; } > "$tmp_out"; '
                 'chmod "$mode" "$tmp_out"; mv "$tmp_out" "$target"; rm -f "$tmp_b64"; '
                 f"printf 'BYTES=%s\\nSHA256=%s\\n' {len(data)} {shlex.quote(sha256)}"
             )
@@ -787,13 +830,16 @@ class SessionManager:
         )
 
     def write(self, session_id: str, text: str, *, owner_agent_id: str | None = None) -> dict[str, object]:
+        return self.send(session_id, f"{text}\n", owner_agent_id=owner_agent_id)
+
+    def send(self, session_id: str, text: str, *, owner_agent_id: str | None = None) -> dict[str, object]:
         session = self._get_session(session_id)
         self._check_owner(session, owner_agent_id)
         if session.busy:
             raise RemoteCommandError(f"session {session_id} is busy")
         if not session.child.isalive():
             raise RemoteCommandError(f"session {session_id} is not alive")
-        session.child.sendline(text)
+        session.child.send(text)
         session.last_used_at = time.time()
         return {"session_id": session_id, "written": True}
 
@@ -851,10 +897,11 @@ class SessionManager:
             raise RemoteCommandError(f"host {host_id} reached session limit {self._max_sessions_per_host}")
 
     def _build_remote_line(self, command: str, token: str, start_marker: str) -> str:
-        quoted_command = shlex.quote(command)
+        encoded_command = base64.b64encode(command.encode("utf-8")).decode("ascii")
         return (
+            f"__scm_cmd=$(printf %s {shlex.quote(encoded_command)} | {{ base64 --decode 2>/dev/null || base64 -D; }}); "
             f"printf '\\n{start_marker}\\n'; "
-            f"{self.remote_shell} -lc {quoted_command}; "
+            f"{self.remote_shell} -lc \"$__scm_cmd\"; "
             "__scm_status=$?; "
             f"printf '\\n__SCM_EXIT_{token}:%s\\n' \"$__scm_status\""
         )

package/src/server_control_mcp/mock_ssh.py

@@ -0,0 +1,647 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import posixpath
+import shlex
+import sys
+import time
+from contextlib import suppress
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import asyncssh
+
+from .daemon import build_manager
+from .manager import DEFAULT_COMMAND_TIMEOUT, RemoteCommandError, SessionManager, _new_token
+
+DEFAULT_PORT_RANGE = range(2222, 2300)
+
+
+class HostBridgeSSHServer(asyncssh.SSHServer):
+    def __init__(self, authorized_public_key: str) -> None:
+        self._authorized_public_key = authorized_public_key.strip()
+
+    def begin_auth(self, username: str) -> bool:  # noqa: ARG002
+        return True
+
+    def public_key_auth_supported(self) -> bool:
+        return True
+
+    def password_auth_supported(self) -> bool:
+        return False
+
+    def validate_public_key(self, username: str, key: asyncssh.SSHKey) -> bool:  # noqa: ARG002
+        return key.export_public_key().decode("utf-8").strip() == self._authorized_public_key
+
+
+class HostBridgeSSHProcess:
+    def __init__(self, manager: SessionManager, session_factory: "HostBridgeSessionFactory", timeout: int, output_limit: int) -> None:
+        self._manager = manager
+        self._session_factory = session_factory
+        self._timeout = timeout
+        self._output_limit = output_limit
+
+    async def __call__(self, process: asyncssh.SSHServerProcess[str]) -> None:
+        session_id = self._session_factory.open()
+        try:
+            await self._run(process, session_id)
+        finally:
+            self._session_factory.close(session_id)
+
+    async def _run(self, process: asyncssh.SSHServerProcess[str], session_id: str) -> None:
+        command = process.command
+        if not command:
+            await self._run_shell(process, session_id)
+            return
+
+        loop = asyncio.get_running_loop()
+        try:
+            result = await loop.run_in_executor(
+                None,
+                lambda: self._manager.run_command(
+                    session_id,
+                    command,
+                    timeout=self._timeout,
+                    token_factory=_new_token,
+                    output_limit=self._output_limit,
+                ),
+            )
+            if result.output:
+                process.stdout.write(result.output)
+                if not result.output.endswith("\n"):
+                    process.stdout.write("\n")
+            process.exit(124 if result.timed_out else int(result.exit_code or 0))
+        except Exception as exc:
+            print(f"hostbridge mock-ssh exec failed: {exc}", file=sys.stderr, flush=True)
+            process.stderr.write(f"hostbridge mock-ssh error: {exc}\n")
+            process.exit(1)
+
+    async def _run_shell(self, process: asyncssh.SSHServerProcess[str], session_id: str) -> None:
+        loop = asyncio.get_running_loop()
+        stop = asyncio.Event()
+        input_done = asyncio.Event()
+
+        async def pump_input() -> None:
+            try:
+                while not process.stdin.at_eof():
+                    data = await process.stdin.read(4096)
+                    if not data:
+                        break
+                    await loop.run_in_executor(
+                        None,
+                        lambda chunk=data: self._manager.send(session_id, chunk, owner_agent_id="mock-ssh"),
+                    )
+            finally:
+                input_done.set()
+
+        async def pump_output() -> None:
+            try:
+                idle_after_input = 0
+                while not stop.is_set():
+                    result = await loop.run_in_executor(
+                        None,
+                        lambda: self._manager.read(
+                            session_id,
+                            timeout=0.2,
+                            max_chars=4096,
+                            owner_agent_id="mock-ssh",
+                        ),
+                    )
+                    output = str(result.get("output") or "")
+                    if output:
+                        idle_after_input = 0
+                        process.stdout.write(output)
+                    elif input_done.is_set():
+                        idle_after_input += 1
+                        if idle_after_input >= 5:
+                            stop.set()
+                            break
+                    if not result.get("alive", True):
+                        stop.set()
+                        break
+            except Exception as exc:
+                print(f"hostbridge mock-ssh shell failed: {exc}", file=sys.stderr, flush=True)
+                process.stderr.write(f"hostbridge mock-ssh shell error: {exc}\n")
+                stop.set()
+
+        tasks = [asyncio.create_task(pump_input()), asyncio.create_task(pump_output())]
+        await stop.wait()
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+        process.exit(0)
+
+
+@dataclass
+class HostBridgeSFTPHandle:
+    path: str
+    readable: bool = False
+    writable: bool = False
+    data: bytes = b""
+    writes: dict[int, bytes] = field(default_factory=dict)
+    mode: int = 0o644
+
+
+class HostBridgeSessionFactory:
+    def __init__(self, manager: SessionManager, host_id: str, connect_timeout: int) -> None:
+        self._manager = manager
+        self._host_id = host_id
+        self._connect_timeout = connect_timeout
+
+    def open(self) -> str:
+        session = self._manager.open_session(
+            self._host_id,
+            connect_timeout=self._connect_timeout,
+            owner_agent_id="mock-ssh",
+        )
+        return session.id
+
+    def close(self, session_id: str) -> None:
+        with _suppress_error():
+            self._manager.close_session(session_id, owner_agent_id="mock-ssh", force=True)
+
+
+class HostBridgeSFTPServer(asyncssh.SFTPServer):
+    def __init__(
+        self,
+        chan: asyncssh.SSHServerChannel,
+        manager: SessionManager,
+        session_factory: HostBridgeSessionFactory,
+        timeout: int,
+        max_bytes: int,
+    ) -> None:
+        super().__init__(chan)
+        self._manager = manager
+        self._session_factory = session_factory
+        self._session_id = session_factory.open()
+        self._timeout = timeout
+        self._max_bytes = max_bytes
+
+    def exit(self) -> None:
+        self._session_factory.close(self._session_id)
+
+    def open(self, path: bytes, pflags: int, attrs: asyncssh.SFTPAttrs) -> HostBridgeSFTPHandle:
+        remote_path = self._path(path)
+        readable = bool(pflags & asyncssh.FXF_READ)
+        writable = bool(pflags & asyncssh.FXF_WRITE)
+        mode = attrs.permissions if attrs.permissions is not None else 0o644
+        data = b""
+        if readable or (writable and not (pflags & asyncssh.FXF_TRUNC) and not (pflags & asyncssh.FXF_CREAT)):
+            try:
+                data = self._download(remote_path)
+            except asyncssh.SFTPNoSuchFile:
+                if not writable:
+                    raise
+                data = b""
+        return HostBridgeSFTPHandle(remote_path, readable=readable, writable=writable, data=data, mode=mode)
+
+    def read(self, file_obj: object, offset: int, size: int) -> bytes:
+        handle = self._handle(file_obj)
+        if not handle.readable:
+            raise asyncssh.SFTPPermissionDenied("file is not open for reading")
+        return handle.data[offset : offset + size]
+
+    def write(self, file_obj: object, offset: int, data: bytes) -> int:
+        handle = self._handle(file_obj)
+        if not handle.writable:
+            raise asyncssh.SFTPPermissionDenied("file is not open for writing")
+        handle.writes[int(offset)] = bytes(data)
+        return len(data)
+
+    def close(self, file_obj: object) -> None:
+        handle = self._handle(file_obj)
+        if handle.writable:
+            self._upload(handle)
+
+    def stat(self, path: bytes) -> asyncssh.SFTPAttrs:
+        return self._stat(self._path(path), follow=True)
+
+    def lstat(self, path: bytes) -> asyncssh.SFTPAttrs:
+        return self._stat(self._path(path), follow=False)
+
+    def fstat(self, file_obj: object) -> asyncssh.SFTPAttrs:
+        handle = self._handle(file_obj)
+        if handle.writable and handle.writes:
+            size = len(handle.data)
+            for offset, chunk in handle.writes.items():
+                size = max(size, offset + len(chunk))
+            return asyncssh.SFTPAttrs(size=size, permissions=handle.mode, type=asyncssh.FILEXFER_TYPE_REGULAR)
+        return self._stat(handle.path, follow=True)
+
+    def fsetstat(self, file_obj: object, attrs: asyncssh.SFTPAttrs) -> None:
+        handle = self._handle(file_obj)
+        if attrs.permissions is not None:
+            handle.mode = attrs.permissions
+        if attrs.atime is not None or attrs.mtime is not None:
+            # Applied after upload in close(); the handle may not exist remotely yet.
+            return
+
+    async def scandir(self, path: bytes):
+        for item in self._listdir(self._path(path)):
+            yield item
+
+    def mkdir(self, path: bytes, attrs: asyncssh.SFTPAttrs) -> None:
+        mode = attrs.permissions if attrs.permissions is not None else 0o755
+        self._checked_run(f"mkdir -p -m {shlex.quote(format(mode & 0o7777, 'o'))} -- {shlex.quote(self._path(path))}")
+
+    def rmdir(self, path: bytes) -> None:
+        self._checked_run(f"rmdir -- {shlex.quote(self._path(path))}")
+
+    def remove(self, path: bytes) -> None:
+        self._checked_run(f"rm -f -- {shlex.quote(self._path(path))}")
+
+    def rename(self, oldpath: bytes, newpath: bytes) -> None:
+        self._checked_run(f"mv -- {shlex.quote(self._path(oldpath))} {shlex.quote(self._path(newpath))}")
+
+    def realpath(self, path: bytes) -> bytes:
+        command = (
+            "python3 -c "
+            + shlex.quote("import os,sys; print(os.path.realpath(sys.argv[1]))")
+            + " "
+            + shlex.quote(self._path(path))
+        )
+        result = self._checked_run(command)
+        return (result.output.strip() or self._path(path)).encode("utf-8")
+
+    def setstat(self, path: bytes, attrs: asyncssh.SFTPAttrs) -> None:
+        remote_path = self._path(path)
+        if attrs.permissions is not None:
+            self._checked_run(f"chmod {shlex.quote(format(attrs.permissions & 0o7777, 'o'))} -- {shlex.quote(remote_path)}")
+        if attrs.atime is not None or attrs.mtime is not None:
+            script = "import os,sys; os.utime(sys.argv[1], (int(sys.argv[2]), int(sys.argv[3])))"
+            current = self._stat(remote_path, follow=True)
+            atime = int(attrs.atime if attrs.atime is not None else current.atime or time.time())
+            mtime = int(attrs.mtime if attrs.mtime is not None else current.mtime or time.time())
+            self._checked_run(f"python3 -c {shlex.quote(script)} {shlex.quote(remote_path)} {atime} {mtime}")
+
+    def _download(self, remote_path: str) -> bytes:
+        try:
+            result = self._manager.file_read_bytes(
+                self._session_id,
+                remote_path,
+                max_bytes=self._max_bytes,
+                token_factory=_new_token,
+                owner_agent_id="mock-ssh",
+            )
+        except RemoteCommandError as exc:
+            raise self._sftp_error(exc) from exc
+        return bytes(result["data_bytes"])
+
+    def _upload(self, handle: HostBridgeSFTPHandle) -> None:
+        size = len(handle.data)
+        for offset, chunk in handle.writes.items():
+            size = max(size, offset + len(chunk))
+        data = bytearray(handle.data)
+        if len(data) < size:
+            data.extend(b"\x00" * (size - len(data)))
+        for offset, chunk in sorted(handle.writes.items()):
+            data[offset : offset + len(chunk)] = chunk
+        try:
+            self._manager.file_write_bytes(
+                self._session_id,
+                handle.path,
+                bytes(data),
+                mode=format(handle.mode & 0o7777, "04o"),
+                max_bytes=self._max_bytes,
+                token_factory=_new_token,
+                owner_agent_id="mock-ssh",
+            )
+        except RemoteCommandError as exc:
+            print(f"hostbridge mock-ssh sftp upload failed: {exc}", file=sys.stderr, flush=True)
+            raise self._sftp_error(exc) from exc
+
+    def _stat(self, remote_path: str, *, follow: bool) -> asyncssh.SFTPAttrs:
+        script = r"""
+import json, os, stat, sys
+path = sys.argv[1]
+st = os.stat(path) if sys.argv[2] == "1" else os.lstat(path)
+print(json.dumps({
+    "size": st.st_size,
+    "permissions": st.st_mode,
+    "uid": st.st_uid,
+    "gid": st.st_gid,
+    "atime": int(st.st_atime),
+    "mtime": int(st.st_mtime),
+    "type": "dir" if stat.S_ISDIR(st.st_mode) else "link" if stat.S_ISLNK(st.st_mode) else "file",
+}))
+"""
+        result = self._checked_run(f"python3 -c {shlex.quote(script)} {shlex.quote(remote_path)} {'1' if follow else '0'}")
+        return self._attrs(json.loads(result.output))
+
+    def _listdir(self, remote_path: str) -> list[asyncssh.SFTPName]:
+        script = r"""
+import json, os, stat, sys, time
+path = sys.argv[1]
+items = []
+for name in os.listdir(path):
+    full = os.path.join(path, name)
+    st = os.lstat(full)
+    item_type = "dir" if stat.S_ISDIR(st.st_mode) else "link" if stat.S_ISLNK(st.st_mode) else "file"
+    items.append({
+        "filename": name,
+        "longname": name,
+        "attrs": {
+            "size": st.st_size,
+            "permissions": st.st_mode,
+            "uid": st.st_uid,
+            "gid": st.st_gid,
+            "atime": int(st.st_atime),
+            "mtime": int(st.st_mtime),
+            "type": item_type,
+        },
+    })
+print(json.dumps(items))
+"""
+        result = self._checked_run(f"python3 -c {shlex.quote(script)} {shlex.quote(remote_path)}")
+        return [
+            asyncssh.SFTPName(item["filename"], item["longname"], self._attrs(item["attrs"]))
+            for item in json.loads(result.output or "[]")
+        ]
+
+    def _attrs(self, data: dict[str, object]) -> asyncssh.SFTPAttrs:
+        permissions = int(data.get("permissions") or 0)
+        raw_type = data.get("type")
+        file_type = {
+            "file": asyncssh.FILEXFER_TYPE_REGULAR,
+            "dir": asyncssh.FILEXFER_TYPE_DIRECTORY,
+            "link": asyncssh.FILEXFER_TYPE_SYMLINK,
+        }.get(str(raw_type), asyncssh.FILEXFER_TYPE_UNKNOWN)
+        return asyncssh.SFTPAttrs(
+            type=file_type,
+            size=int(data.get("size") or 0),
+            uid=int(data.get("uid") or 0),
+            gid=int(data.get("gid") or 0),
+            permissions=permissions,
+            atime=int(data.get("atime") or time.time()),
+            mtime=int(data.get("mtime") or time.time()),
+        )
+
+    def _checked_run(self, command: str):
+        try:
+            result = self._manager.run_command(
+                self._session_id,
+                command,
+                timeout=self._timeout,
+                token_factory=_new_token,
+                owner_agent_id="mock-ssh",
+            )
+        except RemoteCommandError as exc:
+            raise self._sftp_error(exc) from exc
+        if result.timed_out:
+            print(f"hostbridge mock-ssh sftp command timed out: {command}", file=sys.stderr, flush=True)
+            raise asyncssh.SFTPFailure("remote command timed out")
+        if result.exit_code not in (0, None):
+            error = self._sftp_error(RemoteCommandError(result.output or f"remote command exited {result.exit_code}"))
+            if isinstance(error, asyncssh.SFTPNoSuchFile):
+                raise error
+            print(
+                f"hostbridge mock-ssh sftp command failed exit={result.exit_code}: {command}\n{result.output}",
+                file=sys.stderr,
+                flush=True,
+            )
+            raise error
+        return result
+
+    def _path(self, path: bytes) -> str:
+        text = path.decode("utf-8", "surrogateescape")
+        if not text:
+            return "."
+        return posixpath.normpath(text)
+
+    def _handle(self, file_obj: object) -> HostBridgeSFTPHandle:
+        if not isinstance(file_obj, HostBridgeSFTPHandle):
+            raise asyncssh.SFTPInvalidHandle("invalid HostBridge SFTP handle")
+        return file_obj
+
+    def _sftp_error(self, exc: RemoteCommandError) -> Exception:
+        text = str(exc)
+        lowered = text.lower()
+        if "no such file" in lowered or "not found" in lowered or "filenotfounderror" in lowered:
+            return asyncssh.SFTPNoSuchFile(text)
+        if "permission denied" in lowered:
+            return asyncssh.SFTPPermissionDenied(text)
+        return asyncssh.SFTPFailure(text)
+
+
+def ensure_keypair(key_dir: Path) -> tuple[Path, Path, str]:
+    key_dir.mkdir(parents=True, exist_ok=True)
+    with _suppress_chmod_error(key_dir):
+        key_dir.chmod(0o700)
+    host_key_path = key_dir / "ssh_host_ed25519_key"
+    client_key_path = key_dir / "client_ed25519_key"
+    if not host_key_path.exists():
+        host_key = asyncssh.generate_private_key("ssh-ed25519")
+        host_key_path.write_bytes(host_key.export_private_key())
+    if not client_key_path.exists():
+        client_key = asyncssh.generate_private_key("ssh-ed25519")
+        client_key_path.write_bytes(client_key.export_private_key())
+        (key_dir / "client_ed25519_key.pub").write_bytes(client_key.export_public_key())
+    with _suppress_chmod_error(host_key_path):
+        host_key_path.chmod(0o600)
+    with _suppress_chmod_error(client_key_path):
+        client_key_path.chmod(0o600)
+    public_key = (key_dir / "client_ed25519_key.pub").read_text(encoding="utf-8").strip()
+    return host_key_path, client_key_path, public_key
+
+
+def default_key_dir(host_id: str) -> Path:
+    safe_host_id = "".join(ch if ch.isalnum() or ch in "._-" else "_" for ch in host_id)
+    return Path("~/.hostbridge/mock-ssh").expanduser() / safe_host_id
+
+
+def default_ssh_host_alias(host_id: str) -> str:
+    safe_host_id = "".join(ch if ch.isalnum() or ch in ".-" else "-" for ch in host_id).strip(".-")
+    return f"hostbridge-{safe_host_id or 'host'}"
+
+
+async def create_server_on_available_port(
+    *,
+    server_factory,
+    listen_host: str,
+    port: int | None,
+    server_host_keys: list[str],
+    process_factory,
+    sftp_factory,
+):
+    candidates = [port] if port is not None else list(DEFAULT_PORT_RANGE)
+    last_error: OSError | None = None
+    for candidate in candidates:
+        if candidate is None:
+            continue
+        try:
+            server = await asyncssh.create_server(
+                server_factory,
+                listen_host,
+                int(candidate),
+                server_host_keys=server_host_keys,
+                process_factory=process_factory,
+                sftp_factory=sftp_factory,
+                allow_scp=True,
+            )
+            return server, int(candidate)
+        except OSError as exc:
+            last_error = exc
+            continue
+    if port is not None:
+        raise RuntimeError(f"port {port} is not available on {listen_host}") from last_error
+    raise RuntimeError(f"no free port found in {DEFAULT_PORT_RANGE.start}-{DEFAULT_PORT_RANGE.stop - 1}") from last_error
+
+
+def install_ssh_config_block(
+    *,
+    host_alias: str,
+    listen_host: str,
+    port: int,
+    client_key_path: Path,
+    config_path: Path | None = None,
+) -> Path:
+    config_path = config_path or Path("~/.ssh/config").expanduser()
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    existing = config_path.read_text(encoding="utf-8") if config_path.exists() else ""
+    begin = f"# >>> hostbridge mock-ssh {host_alias} >>>"
+    end = f"# <<< hostbridge mock-ssh {host_alias} <<<"
+    block = "\n".join(
+        [
+            begin,
+            f"Host {host_alias}",
+            f"  HostName {listen_host}",
+            f"  Port {port}",
+            "  User hostbridge",
+            f"  IdentityFile {client_key_path}",
+            "  StrictHostKeyChecking no",
+            "  UserKnownHostsFile /dev/null",
+            "  LogLevel ERROR",
+            end,
+            "",
+        ]
+    )
+    _write_text_atomic(config_path, _replace_managed_block(existing, begin, end, block))
+    with _suppress_chmod_error(config_path):
+        config_path.chmod(0o600)
+    return config_path
+
+
+def uninstall_ssh_config_block(host_alias: str, config_path: Path | None = None) -> bool:
+    config_path = config_path or Path("~/.ssh/config").expanduser()
+    if not config_path.exists():
+        return False
+    begin = f"# >>> hostbridge mock-ssh {host_alias} >>>"
+    end = f"# <<< hostbridge mock-ssh {host_alias} <<<"
+    existing = config_path.read_text(encoding="utf-8")
+    updated = _remove_managed_block(existing, begin, end)
+    if updated == existing:
+        return False
+    _write_text_atomic(config_path, updated)
+    return True
+
+
+def _replace_managed_block(existing: str, begin: str, end: str, block: str) -> str:
+    without = _remove_managed_block(existing, begin, end).rstrip()
+    return f"{without}\n\n{block}" if without else block
+
+
+def _remove_managed_block(existing: str, begin: str, end: str) -> str:
+    start = existing.find(begin)
+    if start == -1:
+        return existing
+    stop = existing.find(end, start)
+    if stop == -1:
+        return existing
+    stop += len(end)
+    while stop < len(existing) and existing[stop] in "\r\n":
+        stop += 1
+    return existing[:start].rstrip() + ("\n" if existing[:start].strip() and existing[stop:].strip() else "") + existing[stop:].lstrip()
+
+
+def _write_text_atomic(path: Path, text: str) -> None:
+    tmp_path = path.with_name(f".{path.name}.hostbridge.tmp")
+    tmp_path.write_text(text, encoding="utf-8")
+    tmp_path.replace(path)
+
+
+class _suppress_chmod_error:
+    def __init__(self, path: Path) -> None:
+        self.path = path
+
+    def __enter__(self) -> None:
+        return None
+
+    def __exit__(self, exc_type: object, exc: object, tb: object) -> bool:
+        return exc_type is PermissionError
+
+
+class _suppress_error:
+    def __enter__(self) -> None:
+        return None
+
+    def __exit__(self, exc_type: object, exc: object, tb: object) -> bool:
+        return isinstance(exc, Exception)
+
+
+async def serve_mock_ssh(
+    host_id: str,
+    *,
+    config_path: Path | str | None = None,
+    listen_host: str = "127.0.0.1",
+    port: int | None = None,
+    key_dir: Path | None = None,
+    ssh_host_alias: str | None = None,
+    ssh_config_path: Path | None = None,
+    install_ssh_config: bool = True,
+    connect_timeout: int = 60,
+    command_timeout: int = DEFAULT_COMMAND_TIMEOUT,
+    output_limit: int = 120000,
+) -> int:
+    key_dir = key_dir or default_key_dir(host_id)
+    ssh_host_alias = ssh_host_alias or default_ssh_host_alias(host_id)
+    host_key_path, client_key_path, public_key = ensure_keypair(key_dir)
+    manager = build_manager(config_path)
+    session_factory = HostBridgeSessionFactory(manager, host_id, connect_timeout)
+    try:
+        server, selected_port = await create_server_on_available_port(
+            server_factory=lambda: HostBridgeSSHServer(public_key),
+            listen_host=listen_host,
+            port=port,
+            server_host_keys=[str(host_key_path)],
+            process_factory=HostBridgeSSHProcess(manager, session_factory, command_timeout, output_limit),
+            sftp_factory=lambda chan: HostBridgeSFTPServer(chan, manager, session_factory, command_timeout, output_limit),
+        )
+        installed_config_path: Path | None = None
+        if install_ssh_config:
+            installed_config_path = install_ssh_config_block(
+                host_alias=ssh_host_alias,
+                listen_host=listen_host,
+                port=selected_port,
+                client_key_path=client_key_path,
+                config_path=ssh_config_path,
+            )
+        print(f"hostbridge mock-ssh forwarding host '{host_id}'", flush=True)
+        print(f"listening on ssh://{listen_host}:{selected_port}", flush=True)
+        print(f"ssh host alias: {ssh_host_alias}", flush=True)
+        if installed_config_path is not None:
+            print(f"ssh config: {installed_config_path}", flush=True)
+        print(f"identity file: {client_key_path}", flush=True)
+        print("supports SSH exec, shell, SFTP, and SCP; press Ctrl-C to stop", flush=True)
+        await server.wait_closed()
+    finally:
+        manager.close_all_sessions()
+        manager.stop_idle_reaper()
+    return 0
+
+
+def run_mock_ssh(**kwargs: object) -> int:
+    try:
+        return asyncio.run(serve_mock_ssh(**kwargs))
+    except KeyboardInterrupt:
+        return 130
+    except RemoteCommandError as exc:
+        print(f"hostbridge mock-ssh failed: {exc}")
+        return 1
+
+
+def uninstall_mock_ssh(host_id: str, *, ssh_host_alias: str | None = None, ssh_config_path: Path | None = None) -> int:
+    host_alias = ssh_host_alias or default_ssh_host_alias(host_id)
+    removed = uninstall_ssh_config_block(host_alias, ssh_config_path)
+    print(f"removed SSH config for {host_alias}" if removed else f"no managed SSH config found for {host_alias}")
+    return 0

package/src/server_control_mcp/server.py

@@ -50,6 +50,13 @@ def _daemon_request(method: str, path: str, payload: dict[str, object] | None =
     try:
         return daemon.request_json(method, path, payload, timeout=timeout)
     except OSError as exc:
+        if os.environ.get("HOSTBRIDGE_NPM_LAUNCHER"):
+            socket_path = daemon.socket_path()
+            raise RuntimeError(
+                "hostbridge daemon is not reachable at "
+                f"unix://{socket_path}. Start it outside the MCP sandbox, for example: "
+                f"HOSTBRIDGE_DAEMON_SOCKET={socket_path} npx -y @neoline/hostbridge daemon start --foreground"
+            ) from exc
         # MCP stdout must stay protocol-clean, so auto-start the daemon quietly.
         if daemon.start_background(quiet=True) != 0:
             raise RuntimeError(f"hostbridge daemon failed to start; see {daemon.log_file()}") from exc