ssh-async

OpenCROW I/O - SSH Async

Runtime preflight

Probe required commands with command -v and Python modules with importlib.util.find_spec before use. Prefer a PATH-resolved OpenCROW MCP helper or the ctf/sage environment when available, then the managed helper or system Python. If a capability is missing, stop that path safely and report the exact missing command or module.

Prefer the opencrow-ssh-mcp server for session lifecycle, reads, and writes. Fall back to scripts/sshx only when you need to inspect or debug the backend directly.

MCP First

• Use toolbox_info, toolbox_verify, and toolbox_capabilities first.
• Use the generic session tools:
  • session_start
  • session_send
  • session_read
  • session_status
  • session_stop
• Keep one named session per host/task flow so the MCP server can return stable artifacts under /tmp/opencrow-ssh-async/<name>/.

Use scripts/sshx to manage long-lived SSH sessions instead of one-shot ssh invocations when you are operating outside MCP.

Workflow

1. Start a named session to a remote host.
2. Send shell input while the daemon keeps receiving remote output asynchronously.
3. Read logs with --tail for recent context or --follow for streaming output.
4. Stop the session explicitly when done.

Commands

# Start an interactive login shell
scripts/sshx start --name demo --host 10.0.0.5 --user ubuntu

# Start with a specific identity file and port
scripts/sshx start --name prod --host prod.example.com --user deploy --port 2222 \
  --identity ~/.ssh/deploy_ed25519

# Send a command to the open shell
scripts/sshx send --name prod --data 'uname -a' --newline

# Read recent output
scripts/sshx read --name prod --tail 60

# Follow output live
scripts/sshx read --name prod --follow

# Inspect metadata and process state
scripts/sshx status --name prod

# Stop the session
scripts/sshx stop --name prod

Operational Rules

• Use one session per host/task flow so prompts, working directory, and shell state stay coherent.
• Prefer key-based authentication. The helper runs ssh in batch mode and will fail fast instead of hanging on password prompts.
• Append --newline for normal shell commands.
• Read with --tail before --follow so prompt/output context is visible first.
• Stop sessions explicitly to avoid leaving remote shells running.
• If status reports running: false, inspect daemon.log and io.log before restarting.