nomad
The nomad server enables agentic remote development, allowing AI agents to manage code synchronization, remote command execution, long-running jobs, and network diagnostics on remote machines.
Init & Setup: Discover local workspace details, SSH configs, and proxies (
init_discover); verify SSH connectivity and probe remote hardware/runtimes (init_verify_and_probe); save configuration to.nomad.json(init_save_config).Code Synchronization: Push local code to a remote workspace via incremental
rsync(sync_push); pull remote artifacts into a local project directory (sync_pull).Remote Command Execution: Run short commands on the remote host with output truncation and timeout limits (
run_remote).Long-Running Task Management (via tmux): Start asynchronous tasks in remote tmux sessions (
task_start), check their status and log tail (task_status), list all tasks across targets (task_list), and kill active sessions (task_kill).Reverse SSH Tunnel Management: Start, check status of, and stop persistent reverse SSH tunnels for sharing local proxies with remote jobs (
tunnel_start,tunnel_status,tunnel_stop).Network Diagnostics: Run read-only SSH/network diagnostics for configured remote targets (
net_diagnose).
Enables management of long-running remote tasks through tmux sessions, allowing task start, status, list, and kill operations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@nomad push code to devbox and run tests"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
nomad
nomad is a local MCP server for agentic remote development. It keeps source
code local while an AI agent syncs with rsync, runs commands over SSH, manages
long jobs in remote tmux, and pulls artifacts back into the project.
For Codex, use the project-scoped Streamable HTTP daemon. Stdio remains available for compatible clients and one-off use.
Features
Multiple remote targets per local project.
Project-local
.nomad.jsonconfiguration.SSH preflight checks and read-only network diagnostics.
Incremental
rsyncpush and guarded artifact pull.Short remote commands and long-running
tmuxtasks.Optional persistent reverse SSH tunnels.
Path guards, dangerous-command checks, output limits, and secret redaction.
Related MCP server: ssh-mcp
Requirements
Python 3.11+,
ssh, andrsyncKey-based SSH access to remote targets
Remote
tmuxwhen using long-running tasks
Daemon lifecycle management supports macOS, Linux, and other POSIX systems. Windows is not currently supported or tested.
Installation
Run the latest PyPI release without installing it globally:
uvx --from nomad-mcp nomadOr install an isolated global command:
pipx install nomad-mcpCodex Setup
nomad codex setup is an optional Codex configuration adapter, not a protocol
requirement. Any MCP host can use Nomad through the standard stdio or
Streamable HTTP transports without Codex configuration.
From the project you want Codex to control, run:
nomad codex setup --project "$PWD"
nomad codex doctor --project "$PWD"The adapter starts or repairs a project daemon and writes only the trusted
project's .codex/config.toml. It never changes user-level Codex configuration
or project trust. Resolve any reported global conflict, then fully restart
Codex so it loads the project MCP entry.
Other MCP hosts can launch Nomad directly over stdio:
{
"mcpServers": {
"nomad": {
"command": "uvx",
"args": ["--from", "nomad-mcp", "nomad"]
}
}
}Use nomad client-config to generate JSON or TOML for standard stdio or
Streamable HTTP clients. See Persistent MCP Daemon
for manual registration, lifecycle, security, and troubleshooting.
Quick Start
Start and register the project daemon.
Open Codex in the local project.
Call
health, theninit_discover.Select an SSH target and remote workspace.
Save
.nomad.jsonwithinit_save_config.Push code with
sync_push.Use
run_remotefor short commands.Use
task_startandtask_statusfor long jobs.Pull artifacts with
sync_pull.
Use run_remote only for short synchronous work. Downloads, builds, training,
servers, and batch jobs belong in task_start. If a call with side effects
times out, inspect its status before retrying it.
Documentation
Safety
nomad executes commands over SSH and synchronizes files with rsync. Use it
only with trusted local projects and remote machines. Its guardrails reduce
risk, but cannot make an untrusted agent or host trustworthy.
Development
python -m pip install -e .[dev]
nomad doctor
python -m pytest
python -m compileall -q src testsLicense
MIT
Available Tools
15 toolsinit_discoverA
Pre-scan local workspace environment, .ssh/config aliases and local proxies.
Inputs: no named parameters. Returns: result
init_probe_targetC
Refreshes hardware and runtime snapshot for the specified target.
Inputs: target. Returns: result
init_save_configC
Validates configuration parameters and saves them to .nomad.json.
Inputs: config_json (required). Returns: result
init_verify_and_probeC
Tests connection and probes target system specifications and runtimes.
Inputs: ssh_host (required), remote_path (required), jump_host. Returns: result
net_diagnoseC
Runs read-only SSH/network diagnostics for a configured target.
Inputs: target. Returns: result
run_remoteC
Executes a command on the remote host workspace under target limits.
Inputs: cmd (required), target. Returns: result
sync_pullC
Pulls a remote artifact into a local project-owned directory.
Inputs: remote_relative_path (required), target, local_dest. Returns: result
sync_pushC
Synchronizes local files to the remote workspace target.
Inputs: target. Returns: result
task_killA
Terminates an active tmux session for a task without removing logs/exits or stopping tunnel.
Inputs: task_name (required), target. Returns: result
task_listA
Lists long-running tasks for the given target, or all targets if None.
Inputs: target. Returns: result
task_startC
Starts an asynchronous task under tmux on the remote host.
Inputs: cmd (required), task_name (required), target. Returns: result
task_statusC
Checks the status and reads log tail of a tmux long-running task.
Inputs: task_name (required), target, tail_lines. Returns: result
tunnel_startC
Starts a persistent reverse SSH tunnel for the target.
Inputs: target. Returns: result
tunnel_statusC
Checks the status of the reverse tunnel for the target.
Inputs: target. Returns: result
tunnel_stopC
Stops the persistent reverse SSH tunnel for the target.
Inputs: target. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
All tools have clearly distinct purposes organized by prefixes (init, net, run, sync, task, tunnel). No overlapping functionality exists.
All tool names follow a consistent verb_noun pattern in snake_case with logical prefixes, making them predictable and easy to understand.
With 15 tools, the server is well-scoped for remote workspace management covering initialization, networking, execution, sync, tasks, and tunnels.
The tool surface provides comprehensive lifecycle coverage for tasks (start/list/status/kill) and tunnels (start/status/stop), plus init, sync, and diagnostics.
Maintenance
Related MCP Connectors
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Remote MCP server to run your Atako AI agents: chat, projects, files, integrations and channels.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP server for SSH and local terminal access. Supports interactive commands, long-running processes, and TUI apps like tmux/zellij64MIT
- AlicenseAqualityCmaintenanceAn MCP server that gives AI agents SSH access to remote machines through your local OpenSSH client, enabling remote command execution, file transfer, persistent shell sessions, and port forwarding.17275 PyPI40MIT
- AlicenseBqualityBmaintenanceA comprehensive MCP server for driving tmux sessions, windows, panes, sending keystrokes, and reading pane output locally or over SSH, enabling real-time collaborative pairing with AI.7129 PyPI6MIT
- AlicenseAqualityBmaintenanceSSH orchestration MCP server for coding agents, enabling persistent bash sessions, hash-protected remote file editing, SFTP transfers, SSH tunnels, and multi-host orchestration with connection reuse across tools.148Apache 2.0