Corv v1.1 SSH client for AI agents now supports detached jobs and warm connections

Corv is a command-line SSH client written in Go that bridges the gap between SSH's human-oriented design and the needs of AI agents. Traditional SSH requires the calling workflow to manage connection details, authentication configuration, interactive prompts, and terminal output parsing—tasks that are awkward and error-prone for agents. Additionally, independent SSH invocations repeat the connection setup overhead unless OpenSSH multiplexing is manually configured, and long-running tasks commonly need tmux, nohup, or custom scripts to persist.

Corv's core architecture uses a local broker process that holds one authenticated SSH connection per saved connection profile. Each command (corv <name> -- <cmd>) runs as a new channel over that held connection, so the connection and authentication cost is paid once rather than on every invocation. This behavior is consistent across Windows, macOS, and Linux—unlike OpenSSH's ControlMaster approach, which is limited to Unix. The broker starts automatically on first use and exits after 15 minutes of idle time, installing nothing on the remote server.

Credentials and connection profiles are stored locally and encrypted. Passwords and key passphrases are held in a local encrypted vault (DPAPI-protected on Windows, or using Keychain/Secret Service on macOS and Linux if provisioned). Connection profiles themselves are encrypted so hosts, users, and paths do not leak in plaintext. Secrets are never passed as command-line arguments—agents call corv by connection name, and the credentials remain local.

For long-running jobs, Corv automatically detaches if a command is still executing after the broker's wait window (controlled via the CORV_WAIT environment variable, which accepts bare seconds like 30 or Go durations like 500ms). When detached, Corv returns bounded output, a run id, and exit code 75. Agents can re-run the exact same command to attach to the existing remote job and poll the next delta of output. On completion, Corv retains up to 20 MiB of output locally; if a log exceeds that, it saves the first 4 MiB and the final section with a ... N line(s) hidden ... marker in between, ensuring that late failures are not lost. Completed run logs and metadata are retained for 24 hours and cleaned on broker startup.

Output is normalized for programmatic consumption. Carriage-return redraws (like progress bars) are collapsed to their final state; ANSI control sequences and color codes are stripped; stdout and stderr are captured together and interleaved in write order, returned in stdout, with the --json stderr field reserved for Corv-level errors (not the remote command's own stderr). Bounded byte budgets preserve the beginning and end of output, and structured JSON responses include fields like original_bytes, saved_bytes, returned_bytes, truncated, and output_truncated so agents know exactly what was retained.

For agents, the command syntax is simple: corv <name> -- <command>. Single arguments are treated as a remote shell command line (e.g., corv srv -- "cd /app && make"), while multiple arguments are passed as a preserved vector, shell-quoted to prevent the remote from re-splitting them. For complex scripts, agents can use stdin modes: --stdin for direct input or --stdin-base64 for UTF-8 base64 encoding, which is cross-shell-safe. Agents should never put passwords, tokens, or secrets on the command line; command history records what is passed.

Integrations are provided for Claude and Codex. Claude users copy integrations/claude/corv-ssh into ~/.claude/skills/ (or a project's .claude/skills/). Codex users copy integrations/codex/AGENTS.md into their project. Once integrated, agents run commands by name and read structured JSON output directly. The tool is installed via curl (Linux/macOS), PowerShell (Windows), or Go, and the local broker requires only a POSIX shell and standard Unix tools on remote hosts—Windows OpenSSH servers are not supported as remote execution targets. No server-side software is installed.

Corv addresses a gap in how AI agents interact with infrastructure. SSH is designed around human workflows—users manage keys, negotiate interactive prompts, and parse terminal output—but agents need programmatic interfaces, credential isolation, and connection efficiency. Raw SSH invocations force agents to either handle authentication state themselves or expose secrets in command-line arguments, both poor for security and state management.

The local broker model solves connection reuse without requiring server-side changes (OpenSSH ControlMaster works on Unix but not Windows). By holding one authenticated connection per profile and multiplexing commands over that connection, Corv avoids repeated SSH handshakes and authentication. Detached job support is critical for long-running workflows: agents can start a deployment or install script, poll its status asynchronously, and resume output retrieval at any point, with bounded output handling (first 4 MiB + final section for large logs) so agents do not exhaust memory on verbose remote tasks.

The structured JSON output (with fields like exit_code, original_bytes, saved_bytes, returned_bytes, truncated, and output_truncated) gives agents the metadata they need to determine success, detect truncation, and decide whether to re-query or proceed. The integration paths for Claude and Codex suggest the tool is positioned for immediate adoption in agent-driven infrastructure workflows.

No comments yet. Be the first to share your thoughts!