@neoline/hostbridge 1.1.0 → 1.3.0

package/README.md

@@ -103,12 +103,24 @@ The daemon uses a Unix domain socket with a small JSON-line RPC protocol by defa
 ~/.hostbridge/daemon.sock
 ```
 
-This avoids fixed port conflicts, removes the local HTTP surface, and keeps the control API local to the current machine. The `~/.hostbridge` directory should be private to the local user. To point daemon management commands at a custom socket path:
+When launched through the npm wrapper on macOS, HostBridge sets `HOSTBRIDGE_DAEMON_SOCKET` to `/private/tmp/hostbridge-$USER/daemon.sock` so sandboxed MCP launchers do not accidentally isolate the daemon under a rewritten `HOME`. Python-only launches keep the `~/.hostbridge/daemon.sock` default unless you set `HOSTBRIDGE_DAEMON_SOCKET` or `HOSTBRIDGE_DAEMON_DIR`.
+
+This avoids fixed port conflicts, removes the local HTTP surface, and keeps the control API local to the current machine. The daemon directory should be private to the local user. To point daemon management commands at a custom socket path:
 
 ```bash
 hostbridge daemon start --socket /tmp/hostbridge.sock
 ```
 
+For MCP clients, prefer setting the environment variable instead of relying on symlinks:
+
+```json
+{
+  "env": {
+    "HOSTBRIDGE_DAEMON_SOCKET": "/private/tmp/hostbridge-shengzhoukong/daemon.sock"
+  }
+}
+```
+
 Sessions can outlive a single agent client process. HostBridge records an optional `HOSTBRIDGE_AGENT_ID` owner on sessions and refuses cross-owner operations unless a force-close path is used. Set `HOSTBRIDGE_MAX_SESSIONS_PER_HOST` to cap concurrent live sessions per configured host (default `0`, unlimited).
 
 ## Guided setup wizard

package/bin/hostbridge.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
+import { tmpdir, userInfo } from 'node:os';
 import { dirname, join, delimiter } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -11,6 +12,11 @@ const bundledSrc = join(packageRoot, 'src');
 const moduleDir = join(bundledSrc, 'server_control_mcp');
 const docsUrl = 'https://www.npmjs.com/package/@neoline/hostbridge';
 
+function hostbridgeRuntimeDir(username) {
+  const baseTmp = process.platform === 'darwin' ? '/private/tmp' : tmpdir();
+  return join(baseTmp, `hostbridge-${username}`);
+}
+
 if (!existsSync(moduleDir)) {
   console.error(`hostbridge: bundled Python sources not found at ${moduleDir}`);
   console.error(`  This npm package wraps a Python MCP core. See: ${docsUrl}`);
@@ -21,6 +27,10 @@ const env = { ...process.env };
 env.PYTHONPATH = env.PYTHONPATH ? `${bundledSrc}${delimiter}${env.PYTHONPATH}` : bundledSrc;
 env.HOSTBRIDGE_DEFAULT_MCP_COMMAND = env.HOSTBRIDGE_DEFAULT_MCP_COMMAND || 'npx';
 env.HOSTBRIDGE_DEFAULT_MCP_ARGS = env.HOSTBRIDGE_DEFAULT_MCP_ARGS || JSON.stringify(['-y', '@neoline/hostbridge']);
+if (!env.HOSTBRIDGE_DAEMON_SOCKET && !env.HOSTBRIDGE_DAEMON_DIR) {
+  const username = env.USER || env.LOGNAME || userInfo().username || 'user';
+  env.HOSTBRIDGE_DAEMON_SOCKET = join(hostbridgeRuntimeDir(username), 'daemon.sock');
+}
 
 const child = spawn(pythonPath, ['-m', 'server_control_mcp', ...process.argv.slice(2)], {
   stdio: 'inherit',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neoline/hostbridge",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "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.1.0"
+version = "1.3.0"
 description = "HostBridge MCP server for persistent allowlisted SSH and shell sessions."
 readme = "README.md"
 requires-python = ">=3.11"

package/src/server_control_mcp/__init__.py

@@ -6,7 +6,7 @@ import sys
 from typing import NoReturn
 
 __all__ = ["__version__", "ensure_runtime"]
-__version__ = "1.1.0"
+__version__ = "1.3.0"
 
 # (import_name, pip_name) pairs for runtime dependency probing.
 _REQUIRED_DEPENDENCIES = (

package/src/server_control_mcp/cli.py

@@ -1157,11 +1157,11 @@ def main(argv: list[str] | None = None) -> int:
     daemon_subparsers = daemon_parser.add_subparsers(dest="daemon_command", required=True)
     daemon_start = daemon_subparsers.add_parser("start", help="Start the HostBridge daemon")
     daemon_start.add_argument("--foreground", action="store_true", help="Run daemon in the foreground")
-    daemon_start.add_argument("--socket", dest="socket_file", default=None, help="Unix socket path; default ~/.hostbridge/daemon.sock")
+    daemon_start.add_argument("--socket", dest="socket_file", default=None, help="Unix socket path; default comes from HOSTBRIDGE_DAEMON_SOCKET or HOSTBRIDGE_DAEMON_DIR")
     daemon_stop = daemon_subparsers.add_parser("stop", help="Stop the HostBridge daemon")
-    daemon_stop.add_argument("--socket", dest="socket_file", default=None, help="Unix socket path; default ~/.hostbridge/daemon.sock")
+    daemon_stop.add_argument("--socket", dest="socket_file", default=None, help="Unix socket path; default comes from HOSTBRIDGE_DAEMON_SOCKET or HOSTBRIDGE_DAEMON_DIR")
     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 ~/.hostbridge/daemon.sock")
+    daemon_status.add_argument("--socket", dest="socket_file", default=None, help="Unix socket path; default comes from HOSTBRIDGE_DAEMON_SOCKET or HOSTBRIDGE_DAEMON_DIR")
 
     remove_parser = subparsers.add_parser("remove", parents=[config_parent], help="Remove a configured host")
     remove_parser.add_argument("host_id")

package/src/server_control_mcp/daemon.py

@@ -27,7 +27,7 @@ from .manager import (
 )
 from .policy import build_audit_sink, load_policy
 
-DEFAULT_DAEMON_DIR = Path("~/.hostbridge").expanduser()
+DEFAULT_DAEMON_DIR = Path("~/.hostbridge")
 DEFAULT_SOCKET_FILE = DEFAULT_DAEMON_DIR / "daemon.sock"
 PID_FILE = DEFAULT_DAEMON_DIR / "daemon.pid"
 LOG_FILE = DEFAULT_DAEMON_DIR / "daemon.log"
@@ -280,11 +280,27 @@ def build_manager() -> SessionManager:
     return manager
 
 
+def daemon_dir(path: Path | str | None = None) -> Path:
+    configured = path or os.environ.get("HOSTBRIDGE_DAEMON_DIR") or DEFAULT_DAEMON_DIR
+    return Path(configured).expanduser()
+
+
 def socket_path(path: Path | str | None = None) -> Path:
-    configured = path or os.environ.get("HOSTBRIDGE_DAEMON_SOCKET") or DEFAULT_SOCKET_FILE
+    configured = path or os.environ.get("HOSTBRIDGE_DAEMON_SOCKET")
+    if configured:
+        return Path(configured).expanduser()
+    configured = daemon_dir() / "daemon.sock"
     return Path(configured).expanduser()
 
 
+def pid_file() -> Path:
+    return daemon_dir() / "daemon.pid"
+
+
+def log_file() -> Path:
+    return daemon_dir() / "daemon.log"
+
+
 def _prepare_socket_path(path: Path) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
     with suppress(OSError):
@@ -310,7 +326,7 @@ def run_daemon(*, socket_file: Path | str | None = None) -> int:
     path = socket_path(socket_file)
     _prepare_socket_path(path)
     server = ThreadingUnixRPCServer(str(path), make_handler(manager))
-    PID_FILE.write_text(str(os.getpid()), encoding="utf-8")
+    pid_file().write_text(str(os.getpid()), encoding="utf-8")
     try:
         print(f"hostbridge daemon listening on unix://{path}", flush=True)
         server.serve_forever()
@@ -321,7 +337,7 @@ def run_daemon(*, socket_file: Path | str | None = None) -> int:
         with suppress(FileNotFoundError):
             path.unlink()
         with suppress(FileNotFoundError):
-            PID_FILE.unlink()
+            pid_file().unlink()
     return 0
 
 
@@ -383,7 +399,7 @@ def start_background(*, socket_file: Path | str | None = None, quiet: bool = Fal
     path.parent.mkdir(parents=True, exist_ok=True)
     with suppress(OSError):
         path.parent.chmod(0o700)
-    log_handle = LOG_FILE.open("a", encoding="utf-8")
+    log_handle = log_file().open("a", encoding="utf-8")
     process = subprocess.Popen(
         [sys.executable, "-m", "server_control_mcp", "daemon", "start", "--foreground", "--socket", str(path)],
         stdin=subprocess.DEVNULL,
@@ -392,7 +408,7 @@ def start_background(*, socket_file: Path | str | None = None, quiet: bool = Fal
         start_new_session=True,
         env=os.environ.copy(),
     )
-    PID_FILE.write_text(str(process.pid), encoding="utf-8")
+    pid_file().write_text(str(process.pid), encoding="utf-8")
     deadline = time.time() + 5
     while time.time() < deadline:
         if is_running(socket_file=path):
@@ -401,7 +417,7 @@ def start_background(*, socket_file: Path | str | None = None, quiet: bool = Fal
             return 0
         time.sleep(0.1)
     if not quiet:
-        print(f"hostbridge daemon failed to start; see {LOG_FILE}", file=sys.stderr)
+        print(f"hostbridge daemon failed to start; see {log_file()}", file=sys.stderr)
     return 1
 
 
@@ -411,9 +427,9 @@ def stop_background(*, socket_file: Path | str | None = None) -> int:
         request_json("POST", "/shutdown", timeout=2.0, socket_file=path)
         print("hostbridge daemon stopped")
         return 0
-    if PID_FILE.exists():
+    if pid_file().exists():
         with suppress(Exception):
-            os.kill(int(PID_FILE.read_text(encoding="utf-8").strip()), signal.SIGTERM)
+            os.kill(int(pid_file().read_text(encoding="utf-8").strip()), signal.SIGTERM)
             print("hostbridge daemon process signaled")
             return 0
     print("hostbridge daemon is not running")

package/src/server_control_mcp/server.py

@@ -52,7 +52,7 @@ def _daemon_request(method: str, path: str, payload: dict[str, object] | None =
     except OSError as 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
+            raise RuntimeError(f"hostbridge daemon failed to start; see {daemon.log_file()}") from exc
         return daemon.request_json(method, path, payload, timeout=timeout)