remote-sandbox-mcp

# remote-sandbox-mcp [](https://pypi.org/project/remote-sandbox-mcp/) [](https://pypi.org/project/remote-sandbox-mcp/) A MCP Server that treats remote SSH servers as running sandboxes, supporting: - **Multi-sandbox management**: Configure multiple servers, automatically query CPU/memory/GPU usage, and select the most idle sandbox - **Persistent SSH sessions**: Each sandbox maintains a long connection, automatic health check and reconnection, no need to recreate a new connection every time - **Reliable timeout control**: Double-layer timeout (remote `timeout` command + client deadline) ensures that the timeout really takes effect - **Background long tasks**: Run long tasks in tmux through `exec_bash_background`, default automatic registration watchdog and return `watch_id` - **Intelligent file transfer**: `sync_local_to_remote` only processes small transmissions inline by default; if the threshold is exceeded, it will automatically switch to the local background worker to avoid blocking a single `tools/call`, and retains `excludes` / `exclude_file` rules - **macOS daemon monitoring**: Local `launchd` watchdog continuously monitors remote long tasks, writes status to SQLite, sends local notifications after continuous SSH failures, and resumes according to checkpoint/resume plan when tmux is lost - Local file/directory synchronization to remote sandbox (incremental, skips unchanged files based on `size + mtime`) - Remote file/directory synchronization back to local - Execute bash commands on remote sandbox and return results - Browse remote file lists and read file contents ## 1. Quick Add to Claude Code No need to manually install, directly use `claude mcp add` (depends on [uv](https://docs.astral.sh/uv/) to automatically manage the running environment). ### Single Sandbox ```bash claude mcp add remote-sandbox \ -e REMOTE_HOST=192.168.9.16 \ -e REMOTE_PORT=22 \ -e REMOTE_USER=your_user \ -e REMOTE_PASSWORD=your_password \ -- uvx remote-sandbox-mcp ``` ### Multi-Sandbox ```bash claude mcp add remote-sandbox \ -e REMOTE_SANDBOX_LIST='[{"name":"A100","host":"192.168.9.15","port":22,"user":"ubuntu","password":"xxx"},{"name":"H100","host":"192.168.9.16","port":22,"user":"ubuntu","password":"xxx"}]' \ -- uvx remote-sandbox-mcp ``` Verify after adding: ```bash claude mcp list ``` > **Scope**: Default add to current project (`-s project`). If you want to make it globally available, add `-s user`. > **Update**: Re-execute the same `claude mcp add` command (will overwrite old configuration), or `uvx` automatically pulls the latest version every time. --- ## 2. Manual Installation (Codex/Claude Universal, recommended to do first) ```bash pip install remote-sandbox-mcp # or uv tool install remote-sandbox-mcp ``` If you use a project virtual environment, you can also install it in `.venv`, and then point `command` in Codex configuration to `.venv/bin/remote-sandbox-mcp`. --- ## 3. Codex Configuration Guide (same toolset) Complete the installation in section 2, and then configure Codex MCP. ### Recommended Configuration (TOML) ```toml [mcp_servers."remote-sandbox"] command = "/absolute/path/to/remote-sandbox-mcp" # `which remote-sandbox-mcp` can be used to view enabled = true [mcp_servers."remote-sandbox".env] REMOTE_SANDBOX_LIST = '[{"name":"A100","host":"192.168.9.15","port":22,"user":"ubuntu","password":"xxx"},{"name":"H100","host":"192.168.9.16","port":22,"user":"ubuntu","password":"xxx"}]' ``` ### How to Find `command` Absolute Path ```toml [mcp_servers."remote-sandbox"] command = "/absolute/path/to/python" args = ["-m", "remote_sandbox_mcp.server"] enabled = true ``` ### Verification After connecting, call `list_sandboxes(check_resources=true)` first to confirm that `sandboxes` in the return is not empty. ## 4. Environment Variables Authentication supports **password** and **private key**, provide at least one of `password` and `key_file`; if both are provided, private key is used first. ### Single Sandbox (backward compatible) ```bash # Password authentication export REMOTE_HOST=1.2.3.4 export REMOTE_PORT=22 export REMOTE_USER=your_user export REMOTE_PASSWORD=your_password # Private key authentication export REMOTE_HOST=1.2.3.4 export REMOTE_USER=your_user export REMOTE_KEY_FILE=~/.ssh/id_ed25519 export REMOTE_KEY_PASSPHRASE= # Only fill in if there is encryption passphrase ``` ### Multi-Sandbox (recommended) ```bash export REMOTE_SANDBOX_LIST='[ {"name": "gpu1", "host": "10.0.0.1", "user": "ubuntu", "password": "secret1"}, {"name": "gpu2", "host": "10.0.0.2", "user": "ubuntu", "key_file": "~/.ssh/id_ed25519"}, {"name": "L20", "host": "10.0.0.3", "user": "root", "key_file": "~/.ssh/id_rsa", "key_passphrase": "mypass"} ]' ``` Field description: | Field | Required | Description | |------|------|------| | `name` | No | Sandbox identifier, default uses host | | `host` | Yes | SSH address | | `port` | No | SSH port, default 22 | | `user` | Yes | Username | | `password` | Optional | Password authentication | | `key_file` | Optional | Private key file path (support `~` expansion), support Ed25519 / RSA / ECDSA / DSS | | `key_passphrase` | No | Private key encryption passphrase (leave blank if no encryption) | File transfer threshold related environment variables: | Variable | Default value | Description | |------|------|------| | `REMOTE_SANDBOX_INLINE_SYNC_MAX_FILES` | `200` | Maximum number of files allowed for `sync_local_to_remote` to execute inline, automatically switch to background if exceeded | | `REMOTE_SANDBOX_INLINE_SYNC_MAX_BYTES` | `67108864` | Maximum number of bytes allowed for `sync_local_to_remote` to execute inline, automatically switch to background if exceeded | ## 5. Start MCP Server ```bash remote-sandbox-mcp ``` Use `stdio` transport, suitable for being pulled up by MCP Client as a subprocess. ## 6. MCP Client Configuration Example ### Single Sandbox ```json { "mcpServers": { "remote-sandbox": { "command": "remote-sandbox-mcp", "env": { "REMOTE_HOST": "192.168.9.16", "REMOTE_PORT": "22", "REMOTE_USER": "ubuntu", "REMOTE_PASSWORD": "mypassword" } } } } ``` ### Multi-Sandbox ```json { "mcpServers": { "remote-sandbox": { "command": "remote-sandbox-mcp", "env": { "REMOTE_SANDBOX_LIST": "[{\"name\":\"gpu1\",\"host\":\"10.0.0.1\",\"user\":\"ubuntu\",\"password\":\"s1\"},{\"name\":\"gpu2\",\"host\":\"10.0.0.2\",\"user\":\"ubuntu\",\"password\":\"s2\"}]" } } } } ``` ## 7. Available Tools The default public MCP tools are only these categories: - Sandbox management: `list_sandboxes`, `select_sandbox`, `get_active_sandbox` - Command execution: `exec_bash`, `exec_bash_background`, `check_background_task` - File operation: `list_remote_files`, `read_remote_file`, `sync_local_to_remote`, `check_file_transfer_task`, `cancel_file_transfer_task`, `sync_remote_to_local` This can minimize the tool list and reduce the context burden of Agent. The default return will also be as concise as possible: prioritize retaining status, ID, key paths, and necessary logs, do not echo input parameters by default, and do not attach large internal objects by default. Related advanced operation and maintenance tools for watchdog are **not exposed** by default; `exec_bash_background()` will automatically use them internally. If you really need to manually troubleshoot/operate watchdog, set the environment variable: ```bash export REMOTE_SANDBOX_EXPOSE_ADVANCED_TOOLS=1 ``` ### Sandbox Management #### `list_sandboxes` List all configured sandboxes and connection status. Parameters: - `check_resources` (bool, default `false`): Whether to query CPU/memory/GPU usage and `idle_score` (0=busy, 1=idle) for each sandbox #### `select_sandbox` Set a sandbox as the active sandbox for the current session, and all subsequent tool calls will use it by default. Parameters: - `sandbox_name` (str, required) #### `get_active_sandbox` Return the current active sandbox and its connection health status (`connection_alive`). --- ### Command Execution #### `exec_bash` Execute bash commands on the remote end, suitable for short tasks (< 2 minutes). Note: - MCP Client often adds additional timeout to a single `tools/call`, common values are about 120 seconds. - Therefore, `exec_bash` is more suitable for commands that are "significantly shorter than 120 seconds"; for long tasks, please use `exec_bash_background`. Parameters: - `command` (str, required) - `cwd` (str, optional): Switch to this directory before execution - `timeout_s` (int, default 120): Timeout seconds (double-layer guarantee, really takes effect) - `max_output_chars` (int, default 20000) - `sandbox_name` (str, optional): Temporarily override the active sandbox Return additional fields: `timed_out: true` (when timed out), `connection_error: true` (when connection is disconnected) #### `exec_bash_background` Run long tasks in the background in tmux on the remote end, return immediately. Output is written to the log file through `tee`, and `EXIT_CODE=<n>` is appended at the end. From `0.6.x`, this is the **recommended entry for long tasks**: - Default automatic registration watchdog and return `watch_id` - On macOS, default automatic ensure local `launchd` watchdog is installed and started - If `checkpoint_*` + `resume_command` / `resume_plan_json` is provided, watchdog will continue to check after SSH interruption and recovery, and resume according to the plan when tmux is lost Parameters: - `command` (str, required): Command to be executed - `session_name` (str, optional): tmux session name, default automatically generated (`bg-<timestamp>`) - `log_file` (str, optional): Remote log path, default `.codex_logs/<session_name>.log` - `cwd` (str, optional): Working directory - `sandbox_name` (str, optional) - `watch` (bool, default `true`): Whether to automatically register watchdog - `ensure_watchdog` (bool, default `true`): Whether to automatically install/start local watchdog - `run_id` / `watch_name` (str, optional): Watch stable identifier and display name - `resume_command` (str, optional): Resume command - `resume_plan_json` (str, optional): Structured resume plan - `checkpoint_path` / `checkpoint_command` / `checkpoint_format`: Checkpoint read method - `interval_s` (int, default `300`): Watchdog check interval, default every 5 minutes - `alert_after_failures` (int, default `2`): How many consecutive SSH check failures before sending local notifications/events - `resume_delay_s` (int, default `300`): Wait for how long before trying to resume after tmux is lost - `notify_local` (bool, default `true`): Send local notifications on macOS for severe events - `webhook_url` / `event_command`: Watchdog event callback - `auto_resume` / `max_resume_attempts`: Automatic resume strategy - `metadata_json` (str, optional): Additional JSON metadata - `codex_wakeup` / `codex_command`: Generate local Codex event command for watchdog Default return fields: - `status`: Fixed to `started` - `tmux_session` - `log_file` - `sandbox` - `watch_id`: Only returned when `watch=true` and registration is successful - `launch_recovered`: Only returned when the startup command returns abnormally, but the tmux task seems to be running #### `check_background_task` Query the running status and latest log of the background tmux task. Parameters: - `tmux_session` (str, optional): `exec_bash_background` returned session name - `log_file` (str, optional): Log path (value returned by `exec_bash_background`) - `watch_id` (int, optional): If you have obtained `watch_id`, you can directly pass this - `last_n_lines` (int, default 50): Return the last number of log lines - `sandbox_name` (str, optional) Return fields: - `tmux_session` - `running` - `exit_code`: Parsed from log after task ends; usually empty when running - `log_tail` - `watch_id`: Only returned when you query by `watch_id` - `error` / `connection_error`: Only returned when SSH check fails --- ### Advanced Watchdog Tools (not exposed by default) These tools are used to install a resident watchdog on **macOS**. The watchdog is independent of the MCP `stdio` process, so Codex/Claude sessions will continue to poll background tasks after the session ends. They are not in the MCP tool list by default to avoid wasting context; only when `REMOTE_SANDBOX_EXPOSE_ADVANCED_TOOLS=1` is set, they are exposed. Normally, you **do not need** to manually call `install_macos_watchdog()`. Directly call `exec_bash_background()` to automatically ensure the watchdog is installed/started and registered for this long task. #### `install_macos_watchdog` Optional pre-installation/diagnosis entry: install or refresh `launchd` daemon, and persist sandbox configuration in the local configuration file. Parameters: - `start_now` (bool, default `true`): Start `launchd` agent immediately after installation - `persist_current_sandboxes` (bool, default `true`): Write current `REMOTE_SANDBOX_LIST` / single sandbox environment variables to the local configuration file #### `uninstall_macos_watchdog` Remove `launchd` daemon. #### `get_watchdog_status` View `launchd` status, recent heartbeat, SQLite path, and current watch count. #### `watch_background_task` Registers a long-running task that has already started in a remote `tmux` session, allowing the watchdog to continuously monitor it. It is recommended to provide both `checkpoint` and `resume_plan` so that the watchdog can resume the task according to the plan if it is interrupted remotely. If you are starting a new task, use `exec_bash_background` instead. `watch_background_task` is more suitable for "tasks that are already running remotely and need to be registered with watchdog". Parameters: - `tmux_session` (str, required) - `log_file` (str, required) - `sandbox_name` (str, optional): defaults to the current active sandbox - `run_id` (str, optional): a stable identifier for the long-running task - `name` (str, optional): a watch name for easy identification - `cwd` (str, optional): the remote working directory for the recovery command - `launch_command` (str, optional): the original launch command - `resume_command` (str, optional): the command to re-execute after interruption - `resume_plan_json` (str, optional): a structured recovery plan, recommended to include at least `resume_command` and checkpoint information - `checkpoint_path` (str, optional): the remote checkpoint file path - `checkpoint_format` (str, default `text`): `text` or `json` - `checkpoint_command` (str, optional): a shell command to read the checkpoint if custom logic is needed - `interval_s` (int, default `300`): the check interval, defaulting to every 5 minutes - `max_log_lines` (int, default `80`) - `webhook_url` (str, optional): POST JSON when an event is received - `event_command` (str, optional): a shell command to execute locally when an event is received - `auto_resume` (bool, default `false`): automatically attempt `resume_command` when the remote recovery is connectable and tmux is lost - `max_resume_attempts` (int, default `1`) - `ensure_watchdog` (bool, default `true`): automatically ensure that `launchd` watchdog is running if the local machine is macOS - `notify_local` (bool, default `true`): send local notifications for severe events - `alert_after_failures` (int, default `2`): alert after how many consecutive SSH failures - `resume_delay_s` (int, default `300`): wait for how many seconds before resuming after tmux is lost - `metadata_json` (str, optional): additional JSON metadata #### `exec_bash_background_watch` A compatible alias for `exec_bash_background`. New code is recommended to directly call `exec_bash_background`. Parameters: - Inherits `command`, `session_name`, `log_file`, `cwd`, `sandbox_name` from `exec_bash_background` - Inherits `run_id`, `watch_name`, `resume_command`, `resume_plan_json`, `checkpoint_path`, `checkpoint_format`, `checkpoint_command`, `interval_s`, `webhook_url`, `event_command`, `auto_resume`, `max_resume_attempts`, `metadata_json` from `watch_background_task` - `ensure_watchdog` (bool, default `true`): automatically install/launch local watchdog - `codex_wakeup` (bool, default `false`): enable only when you explicitly want another local Codex to handle events #### `list_background_watches` List all watches. Parameters: `status` (optional) #### `get_background_watch` View a single watch. Parameters: `watch_id` #### `cancel_background_watch` Stop monitoring a watch. Parameters: `watch_id` #### `list_background_watch_events` View watchdog events. Parameters: `watch_id` (optional), `limit` #### `get_background_watch_progress` Read the current progress of a watch, returning: - The recent state stored in SQLite - The current remote log tail - The current checkpoint snapshot Parameters: - `watch_id` - `refresh_live` (bool, default `true`) - `log_lines` (int, default `80`) #### `read_background_watch_log` Read the latest remote log tail of a watch. Parameters: - `watch_id` - `last_n_lines` #### `read_background_watch_checkpoint` Read the latest checkpoint snapshot of a watch. Parameters: - `watch_id` - `max_bytes` Watchdog events are written to local SQLite and event JSON is stored in `events/` under the `db_path` directory. If `event_command` is set, watchdog will append the following environment variables: - `RSMCP_EVENT_FILE` - `RSMCP_EVENT_JSON` - `RSMCP_EVENT_TYPE` - `RSMCP_WATCH_ID` - `RSMCP_SANDBOX_NAME` - `RSMCP_TMUX_SESSION` - `RSMCP_LOG_FILE` - `RSMCP_SUGGESTED_PROMPT` If you explicitly need another local Codex to handle events, you can set `event_command` to: ```sh codex exec "$RSMCP_SUGGESTED_PROMPT" ``` #### Recommended Long-Running Task Script Conventions To make watchdog's automatic recovery reliable, it is recommended that each long-running task meets the following conventions: 1. Break down the actual work into repeatable slices, rather than putting all logic into a non-recoverable large loop. 2. Continuously write logs and keep `EXIT_CODE=<n>` at the end of the log, so that watchdog can distinguish between "completed" and "tmux interrupted". 3. Continuously write checkpoints. Simple tasks can write text; complex tasks are recommended to write JSON, recording completed slices, remaining queues, and product paths. 4. Provide a `resume_command` or `resume_plan_json.resume_command`. This command should read the checkpoint and only continue to do the unfinished part. 5. The resume script should recreate the same tmux session. Watchdog will use the original `tmux_session` name to launch the recovery task by default. A simplified example: ```bash python train.py \ --workdir runs/exp-01 \ --checkpoint runs/exp-01/progress.json \ --resume ``` The corresponding MCP call can be: ```json { "command": "python train.py --workdir runs/exp-01 --checkpoint runs/exp-01/progress.json", "cwd": "~/sandboxes/project", "checkpoint_path": "runs/exp-01/progress.json", "checkpoint_format": "json", "resume_command": "python train.py --workdir runs/exp-01 --checkpoint runs/exp-01/progress.json --resume", "auto_resume": true } ``` Default recovery process: - Watchdog checks the task status every 5 minutes - After 2 consecutive SSH checks fail, trigger an event and send a local notification on macOS - After the connection is restored, if the tmux session has disappeared and there is no `EXIT_CODE=...` in the log, watchdog will wait for `resume_delay_s` to expire and then launch `resume_command` with the original session name --- ### File Operations All file operation tools have added a `sandbox_name` parameter (optional, temporarily overriding the active sandbox). #### `list_remote_files` List remote directory contents. Returned fields: - `entries`: each item contains `path`, `is_dir`, `size`, `mtime` - `truncated`: `true` when the `max_entries` limit is reached Parameters: `remote_path`, `recursive`, `max_entries`, `sandbox_name` #### `read_remote_file` Read a remote file. Returned fields: - `size` - `truncated` - `content` Parameters: `remote_path`, `max_bytes`, `sandbox_name` #### `sync_local_to_remote` This is the default entry, but it is no longer equivalent to "always synchronously upload". Behavior: - Small transfers will be executed inline and return the result directly after the upload is complete - The tool will scan the number of local files to be transferred and the total bytes - `excludes` / `exclude_file` will apply to both inline mode and actual upload after automatically switching to background - As long as one of the following thresholds is exceeded, it will automatically switch to background worker: `REMOTE_SANDBOX_INLINE_SYNC_MAX_FILES`, default `200` `REMOTE_SANDBOX_INLINE_SYNC_MAX_BYTES`, default `64 MiB` Note: - The original "synchronously transfer SFTP once and then return" mode is only suitable for small file transfers. - If the directory is large, there are many files, or the network RTT is high, forcing inline can easily be interrupted by MCP Client's `tools/call` timeout. - It is recommended to use `excludes` / `exclude_file` to exclude large directories and reduce unnecessary scanning and uploading. Returns: - Small transfer: returns `mode=inline` and upload summary - Large transfer: returns `mode=background`, `task_id`, `status`, `pid`, `log_file`, and `auto_switched=true` Local file or directory synchronization to remote (SFTP, incremental). Parameters: `local_path`, `remote_path`, `delete_extras`, `excludes`, `exclude_file`, `sandbox_name` #### `check_file_transfer_task` Query the status of a background file synchronization task and return the local log tail. Parameters: `task_id`, `last_n_lines` Returned fields: - `status`: `queued` / `running` / `completed` / `failed` / `cancelled` - `running`: only returns `true` when the worker is still running - `pending`: only returns `true` when the task has been created but the worker has not yet entered the running state - `stale`: only returns `true` when the database is still `running`, but the worker process no longer exists - `progress`: the latest progress snapshot written - `result`: a concise result summary after the task is completed - `error`: an error summary when the task fails - `log_tail`: local log tail #### `cancel_file_transfer_task` Terminate a background file synchronization task. Behavior: - If the task is still running, try to terminate the local worker process group first - If it still does not exit after `SIGTERM`, upgrade to `SIGKILL` after `force_kill_after_s` expires - After the worker exits, the task status in the database will be updated to `cancelled` - If the worker still survives after termination, the tool will return an error summary and retain the original state Parameters: `task_id`, `force_kill_after_s` Returned fields: - `task_id` - `status`: `cancelled` after successful cancellation - `terminated`: returns `true` when a termination signal is actually sent - `force_killed`: returns `true` when upgraded to `SIGKILL` - `already_finished`: returns `true` if the task has already ended - `error`: error summary when cancellation fails #### `sync_remote_to_local` Synchronize remote files or directories to local (SFTP, incremental). Parameters: `remote_path`, `local_path`, `excludes`, `exclude_file`, `sandbox_name` --- ## 8. Typical Workflow for Multiple Sandboxes ``` 1. list_sandboxes(check_resources=True) → View idle_score, GPU occupancy, etc. for each sandbox 2. select_sandbox(sandbox_name="gpu1") → Choose the most idle sandbox, and subsequent calls will use it 3. get_active_sandbox() → Confirm that the connection is normal (connection_alive: true) 4. exec_bash_background( command="python train.py --epochs 100", cwd="~/projects/mymodel", session_name="train-001" ) → Start in the background, return immediately {tmux_session, log_file, watch_id} 5. check_background_task( watch_id=<id> ) → Poll every few minutes to view log tail and running status ``` ## 9. macOS Watchdog Workflow ```text 1. exec_bash_background( command="python train.py --epochs 100", cwd="~/projects/mymodel", run_id="train-001", watch_name="train-001", auto_resume=true, checkpoint_path="~/projects/mymodel/run_state.json", checkpoint_format="json", resume_command="bash scripts/resume_train.sh", resume_plan_json='{"resume_command":"bash scripts/resume_train.sh","checkpoint_path":"~/projects/mymodel/run_state.json","checkpoint_format":"json"}' ) → Launch tmux task remotely → If the local watchdog is not installed, it will be automatically installed/started → Automatically register watchdog, return watch_id 2. check_background_task(watch_id=<id>) → Directly query remote task status by watch_id 3. get_watchdog_status() → View if launchd is normal, recent heartbeat is fresh 4. get_background_watch_progress(watch_id=<id>) → View current log tail + checkpoint + recent state 5. list_background_watch_events(watch_id=<id>) → View events like ssh_unreachable / interrupted / resume_started / completed ``` If you want to install the local `launchd` watchdog in advance or manually check the daemon status, call `install_macos_watchdog()` separately. ## 10. Precautions - The first connection will automatically accept the host fingerprint (`AutoAddPolicy`). It is recommended to change to a fixed known_hosts check in a production environment. - Background tasks require `tmux` to be installed remotely (most Linux distributions have it by default). - `delete_extras=true` will delete files on the remote that are not present locally, please use with caution. - Persistent sessions perform a health check every 30 seconds, and the next tool call will automatically reconnect after disconnection. - For long-running tasks that need automatic recovery, it is recommended to always provide `checkpoint_path` and `resume_plan_json`; otherwise, watchdog can only detect failure and cannot reliably recover. - Watchdog will persist sandbox credentials to local configuration files; the current implementation does not integrate with system keychain; please ensure that the local user directory permissions are secure. - `event_command` is a local shell command and should only point to trusted scripts or `codex` / `python` executables.