@neoline/hostbridge 0.2.1 → 1.0.0

package/README.md

@@ -17,6 +17,10 @@ This repo is portable: it ships with no personal server paths or built-in hosts.
 - `task_stop(session_id, task_id)` — terminate a running background job and reap its process.
 - `session_write(session_id, text)` — send a raw line for interactive edge cases.
 - `session_read(session_id, timeout=1.0, max_chars=20000)` — read available raw output after interactive writes.
+- `file_write_text(session_id, remote_path, content)` — write a small UTF-8 text file through the active shell.
+- `file_read_text(session_id, remote_path)` — read a small UTF-8 text file through the active shell.
+- `file_upload(session_id, local_path, remote_path)` — upload a small local file with shell/base64 transfer.
+- `file_download(session_id, remote_path, local_path)` — download a small remote file with shell/base64 transfer.
 - `session_close(session_id)` — close a persistent session.
 
 Every tool returns a structured payload with a stable `error_code` on failure (`HOST_NOT_FOUND`, `SESSION_NOT_FOUND`, `POLICY_DENIED`, `TASK_NOT_FOUND`, `TIMEOUT`, `INTERNAL`).
@@ -70,6 +74,43 @@ python3 -m server_control_mcp.server install
 npm run test:node
 ```
 
+
+
+## File transfer model
+
+HostBridge file transfer is shell-based because recorded login paths may be JumpServer menus, OTP flows, wrapper scripts, or `docker exec` sessions rather than standard SSH/SFTP connections. The first-class transfer tools therefore use base64 through the already-open shell session and work best for scripts, configs, logs, and small artifacts:
+
+```bash
+file_upload(session_id, "/absolute/local/script.py", "/remote/work/script.py")
+file_download(session_id, "/remote/work/result.log", "/absolute/local/result.log")
+```
+
+Large files 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.
+
+## Daemon lifecycle
+
+HostBridge always keeps remote sessions in the local daemon. The MCP server process is only a lightweight stdio adapter for agent clients and talks to the daemon over a Unix domain socket. If the daemon is not already running, the MCP adapter starts it lazily on the first tool call.
+
+```bash
+hostbridge daemon start
+hostbridge daemon status
+hostbridge daemon stop
+```
+
+The daemon uses a Unix domain socket with a small JSON-line RPC protocol by default, not HTTP and not a TCP port:
+
+```text
+~/.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:
+
+```bash
+hostbridge daemon start --socket /tmp/hostbridge.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
 
 Run the local setup wizard instead of hand-writing `hosts.json`:
@@ -121,9 +162,10 @@ Recommended agent flow:
 
 1. Call `hosts_list`.
 2. If the target host exists, call `session_open`.
-3. If it does not exist and the user identifies a similar bastion-backed host, run `hostbridge setup <new_id> --from-host <source_id> --menu-selection <ip-or-name> --final-prompt <regex>`.
-4. Call `hosts_list` again, then `session_open(<new_id>)`.
-5. Do not inspect `~/.ssh`, old expect scripts, or shell snapshots unless the user explicitly asks or the setup command lacks required information.
+3. If `session_open` times out or fails, run `hostbridge check <host_id>` to verify the recorded login path, then retry or repair setup.
+4. If it does not exist and the user identifies a similar bastion-backed host, run `hostbridge setup <new_id> --from-host <source_id> --menu-selection <ip-or-name> --final-prompt <regex>`.
+5. Call `hosts_list` again, then `session_open(<new_id>)`.
+6. Do not inspect `~/.ssh`, old expect scripts, or shell snapshots unless the user explicitly asks or the setup command lacks required information.
 
 ### Encrypted login automation
 
@@ -269,6 +311,8 @@ Codex config written by the installer, for example in `~/.codex/config.toml`:
 [mcp_servers.hostbridge]
 command = "npx"
 args = ["-y", "hostbridge"]
+[mcp_servers.hostbridge.env]
+HOSTBRIDGE_AGENT_ID = "codex"
 ```
 
 Claude Desktop style config:
@@ -278,7 +322,8 @@ Claude Desktop style config:
   "mcpServers": {
     "hostbridge": {
       "command": "npx",
-      "args": ["-y", "hostbridge"]
+      "args": ["-y", "hostbridge"],
+      "env": {"HOSTBRIDGE_AGENT_ID": "claude-code"}
     }
   }
 }
@@ -295,7 +340,7 @@ See `examples/` for copyable config templates.
 
 ## Policy, audit, and idle reaping
 
-hostbridge ships a lightweight policy layer that runs in the same process as the MCP server. It is on by default and can be tuned or disabled via environment variables or a JSON config file.
+hostbridge ships a lightweight policy layer that runs inside the daemon process. It is on by default and can be tuned or disabled via environment variables or a JSON config file.
 
 Environment variables:
 
@@ -327,11 +372,12 @@ See `SECURITY.md` and `docs/THREAT_MODEL.md` for the trust model and audited eve
 1. Call `hosts_list` and choose a configured host id.
 2. If the host is missing, ask for only the missing fields and use `hostbridge setup <host_id>` rather than manually editing config.
 3. Call `session_open` once for the chosen host.
-4. Use `command_run` for quick commands such as `nvidia-smi`, `pwd`, `df -h`, or `tmux ls`.
-5. Use `task_start` for long training jobs, downloads, builds, or scripts.
-6. Poll `task_status` until `state` is `finished`; inspect `exit_code` and `log_tail`.
-7. Call `task_stop` early if a job should be aborted.
-8. Call `session_close` when finished, or `sessions_close_all` to tear down every session.
+4. Only if `session_open` times out or fails, run `hostbridge check <host_id>` and retry after fixing the login path.
+5. Use `command_run` for quick commands such as `nvidia-smi`, `pwd`, `df -h`, or `tmux ls`.
+6. Use `task_start` for long training jobs, downloads, builds, or scripts.
+7. Poll `task_status` until `state` is `finished`; inspect `exit_code` and `log_tail`.
+8. Call `task_stop` early if a job should be aborted.
+9. Call `session_close` when finished, or `sessions_close_all` to tear down every session.
 
 ## Security notes
 
@@ -347,4 +393,4 @@ See `CONTRIBUTING.md`. Run tests with `python -m pytest -q`. The full suite shou
 
 ## License
 
-MIT. See `LICENSE`.
+MIT. See `LICENSE`.

package/examples/claude_desktop_config.json

@@ -2,7 +2,10 @@
   "mcpServers": {
     "hostbridge": {
       "command": "npx",
-      "args": ["-y", "hostbridge"]
+      "args": ["-y", "hostbridge"],
+      "env": {
+        "HOSTBRIDGE_AGENT_ID": "claude-code"
+      }
     }
   }
 }

package/examples/codex.config.toml

@@ -1,7 +1,7 @@
 [mcp_servers.hostbridge]
 command = "npx"
 args = ["-y", "hostbridge"]
-
+[mcp_servers.hostbridge.env]
+HOSTBRIDGE_AGENT_ID = "codex"
 # Optional: use a project-specific host file instead of ~/.hostbridge/hosts.json
-# [mcp_servers.hostbridge.env]
 # HOSTBRIDGE_HOSTS_FILE = "/absolute/path/to/hosts.json"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neoline/hostbridge",
-  "version": "0.2.1",
+  "version": "1.0.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 = "0.2.1"
+version = "1.0.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__ = "0.2.1"
+__version__ = "1.0.0"
 
 # (import_name, pip_name) pairs for runtime dependency probing.
 _REQUIRED_DEPENDENCIES = (

package/src/server_control_mcp/__main__.py

@@ -1,16 +1,19 @@
 from __future__ import annotations
 
+import sys
+
 from . import ensure_runtime
 
 
-def main() -> None:
+def main() -> int:
     ensure_runtime()
     # Imported lazily so a missing mcp/pexpect/cryptography dependency surfaces
     # the friendly ensure_runtime() message instead of a raw ImportError.
     from .server import main as server_main
 
-    server_main()
+    result = server_main()
+    return result if isinstance(result, int) else 0
 
 
 if __name__ == "__main__":
-    main()
+    sys.exit(main())

package/src/server_control_mcp/cli.py

@@ -35,9 +35,11 @@ Use HostBridge when the user asks to connect to, inspect, or operate an allowlis
 
 - First call `hosts_list` to see configured hosts; then use `session_open("<host_id>")`.
 - If the host is missing, ask only for the missing connection details and run `hostbridge setup <host_id>` instead of editing JSON by hand.
-- Validate host entries with `hostbridge check <host_id>` before relying on them.
+- Do not run `hostbridge check` before every connection; only use `hostbridge check <host_id>` when `session_open` times out or fails.
 - Do not search shell history, SSH config, or old scripts unless the setup flow lacks required information or the user explicitly asks.
 - Keep long-running work in `task_start`/`task_status`; use `session_close` or `sessions_close_all` when done.
+- Use `file_write_text`/`file_read_text` for small UTF-8 files and `file_upload`/`file_download` for small binary or text artifacts.
+- Do not use HostBridge file tools for large model/data transfers; start a remote pull instead (`curl`, `wget`, `git clone`, `modelscope download`, etc.) and poll it with `task_status`.
 {HOSTBRIDGE_GUIDANCE_END}
 """
 SUPPORTED_INSTALL_TARGETS = (
@@ -51,7 +53,7 @@ SUPPORTED_INSTALL_TARGETS = (
     "antigravity",
     "kiro",
 )
-SETUP_COMMANDS = {"install", "setup", "check", "list", "remove", "reload", "secret", "step"}
+SETUP_COMMANDS = {"install", "setup", "check", "list", "remove", "reload", "secret", "step", "daemon"}
 AskFunc = Callable[[str], str]
 SecretAskFunc = Callable[[str], str]
 VerifyFunc = Callable[[dict[str, object], int], "VerificationResult"]
@@ -268,11 +270,13 @@ def _toml_array(values: list[str]) -> str:
     return "[" + ", ".join(_toml_quote(value) for value in values) + "]"
 
 
-def _server_control_block(command: str, args: list[str]) -> str:
+def _server_control_block(command: str, args: list[str], *, agent_id: str) -> str:
     return "\n".join([
         f"[mcp_servers.{PUBLIC_NAME}]",
         f"command = {_toml_quote(command)}",
         f"args = {_toml_array(args)}",
+        f"[mcp_servers.{PUBLIC_NAME}.env]",
+        f"HOSTBRIDGE_AGENT_ID = {_toml_quote(agent_id)}",
         "",
     ])
 
@@ -360,27 +364,28 @@ def _remove_legacy_mcp_server_keys(value: object) -> None:
             _remove_legacy_mcp_server_keys(child)
 
 
-def _install_codex_config(config_path: Path, command: str, args: list[str]) -> None:
-    block = _server_control_block(command, args)
+def _install_codex_config(config_path: Path, command: str, args: list[str], *, agent_id: str) -> None:
+    block = _server_control_block(command, args, agent_id=agent_id)
     existing = config_path.read_text(encoding="utf-8") if config_path.exists() else ""
     updated = _remove_toml_table(existing, f"[mcp_servers.{LEGACY_PUBLIC_NAME}]")
     updated = _remove_toml_table(updated, f"[mcp_servers.{LEGACY_PACKAGE_NAME}]")
+    updated = _remove_toml_table(updated, f"[mcp_servers.{PUBLIC_NAME}.env]")
     updated = _replace_toml_table(updated, f"[mcp_servers.{PUBLIC_NAME}]", block)
     config_path.parent.mkdir(parents=True, exist_ok=True)
     config_path.write_text(updated, encoding="utf-8")
 
 
-def _install_mcp_servers_json(config_path: Path, command: str, args: list[str]) -> None:
+def _install_mcp_servers_json(config_path: Path, command: str, args: list[str], *, agent_id: str) -> None:
     data = _read_json_object(config_path)
     _remove_legacy_mcp_server_keys(data)
     servers = data.setdefault("mcpServers", {})
     if not isinstance(servers, dict):
         raise ValueError(f"{config_path} mcpServers must be an object")
-    servers[PUBLIC_NAME] = {"command": command, "args": args}
+    servers[PUBLIC_NAME] = {"command": command, "args": args, "env": {"HOSTBRIDGE_AGENT_ID": agent_id}}
     _write_json_object(config_path, data)
 
 
-def _install_opencode_config(config_path: Path, command: str, args: list[str]) -> None:
+def _install_opencode_config(config_path: Path, command: str, args: list[str], *, agent_id: str) -> None:
     data = _read_json_object(config_path)
     servers = data.setdefault("mcp", {})
     if not isinstance(servers, dict):
@@ -391,6 +396,7 @@ def _install_opencode_config(config_path: Path, command: str, args: list[str]) -
         "type": "local",
         "command": [command, *args],
         "enabled": True,
+        "env": {"HOSTBRIDGE_AGENT_ID": agent_id},
     }
     _write_json_object(config_path, data)
 
@@ -420,11 +426,11 @@ def _agent_install_specs(home: Path) -> list[AgentInstallSpec]:
 
 def _install_spec(spec: AgentInstallSpec, command: str, args: list[str]) -> None:
     if spec.kind == "codex_toml":
-        _install_codex_config(spec.path, command, args)
+        _install_codex_config(spec.path, command, args, agent_id=spec.target)
     elif spec.kind == "opencode_json":
-        _install_opencode_config(spec.path, command, args)
+        _install_opencode_config(spec.path, command, args, agent_id=spec.target)
     else:
-        _install_mcp_servers_json(spec.path, command, args)
+        _install_mcp_servers_json(spec.path, command, args, agent_id=spec.target)
     if spec.guidance_path is not None:
         _install_guidance_file(spec.guidance_path)
 
@@ -458,7 +464,7 @@ def run_install(
 
     if target == "codex":
         resolved_config = Path(config_path or DEFAULT_CODEX_CONFIG).expanduser()
-        _install_codex_config(resolved_config, resolved_command, resolved_args)
+        _install_codex_config(resolved_config, resolved_command, resolved_args, agent_id="codex")
         label = "Codex"
     else:
         home = Path(home_path or Path.home()).expanduser()
@@ -982,6 +988,24 @@ def run_reload() -> int:
     return 0
 
 
+def run_daemon_command(command: str, *, foreground: bool = False, socket_file: Path | str | None = None) -> int:
+    from . import daemon
+
+    if command == "start":
+        if foreground:
+            return daemon.run_daemon(socket_file=socket_file)
+        return daemon.start_background(socket_file=socket_file)
+    if command == "stop":
+        return daemon.stop_background(socket_file=socket_file)
+    if command == "status":
+        if daemon.is_running(socket_file=socket_file):
+            print(f"hostbridge daemon running at unix://{daemon.socket_path(socket_file)}")
+            return 0
+        print("hostbridge daemon is not running")
+        return 1
+    raise ValueError(f"unknown daemon command: {command}")
+
+
 
 def run_entry_login_steps(child: object, entry: dict[str, object], timeout: int) -> None:
     raw_steps = entry.get("login_steps", [])
@@ -1128,6 +1152,16 @@ def main(argv: list[str] | None = None) -> int:
     subparsers.add_parser("list", parents=[config_parent], help="List configured hosts")
     subparsers.add_parser("reload", help="Explain runtime host reload behavior")
 
+    daemon_parser = subparsers.add_parser("daemon", help="Manage the HostBridge daemon")
+    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_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_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")
+
     remove_parser = subparsers.add_parser("remove", parents=[config_parent], help="Remove a configured host")
     remove_parser.add_argument("host_id")
 
@@ -1176,6 +1210,12 @@ def main(argv: list[str] | None = None) -> int:
         return run_remove(args.host_id, config_path=config_path)
     if args.command == "reload":
         return run_reload()
+    if args.command == "daemon":
+        return run_daemon_command(
+            args.daemon_command,
+            foreground=getattr(args, "foreground", False),
+            socket_file=getattr(args, "socket_file", None),
+        )
     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)