For AI Agents

AI Agent Instructions

Add this page to your AI agent's context to enable SSH operations via sshDCommander. Copy the URL or the content below into your CLAUDE.md, .cursorrules, or system prompt.

What is sshDCommander?

sshDCommander v3.5.1 is a persistent SSH daemon with three CLI tools. It keeps SSH connections alive between your tool calls so you never reconnect. Server profiles store credentials securely in the OS keyring — no passwords in prompts.

Best practices for AI agents

Use script mode (-s) for complex commands

Commands with pipes, quotes, semicolons, variable expansion, or special characters like {} | ; $ " ' < > [ ] \\ ` & will break when passed inline — shell metacharacters get re-interpreted at each layer.

Use the -s (script mode) flag. This wraps your command in a temporary script, uploads it, executes it on the server, and cleans up automatically.

# BAD: inline complex command breaks
sshdcmd --client-id claude "cat /etc/nginx/sites-enabled/* | grep server_name"
# GOOD: script mode handles it safely
sshdcmd --client-id claude -s "cat /etc/nginx/sites-enabled/* | grep server_name"

Use temporary files for multi-line scripts

For scripts longer than one line, write a local temp file, upload it with sshdcp, execute it, and clean up. This avoids all quoting and escaping issues entirely.

# Write script locally, upload, execute, clean up
sshdcp --client-id claude upload ./deploy.sh /tmp/deploy.sh
sshdcmd --client-id claude "bash /tmp/deploy.sh && rm /tmp/deploy.sh"

UTF-8 without BOM

All files uploaded to Linux servers must be UTF-8 without BOM. sshDCommander auto-strips BOM on upload, but ensure your local file generation uses UTF-8 without BOM to avoid issues.

First command needs --connect

The first sshdcmd call to a server must include --connect to establish the SSH session. All subsequent commands reuse the connection automatically. Do not pass --connect again.

Three CLI tools

sshDCommander CLI tools
sshdcmd — Execute remote commands
sshdcmd --client-id YOUR_ID "COMMAND" [--server NAME] [--connect]
sshdcp — Transfer files with SHA-256 verification
sshdcp --client-id YOUR_ID upload|download LOCAL REMOTE [--server NAME]
sshdctl — Manage daemon, servers, licenses
sshdctl start-daemon | connect | server add | status | done

Required: --client-id

Every sshdcmd and sshdcp call requires --client-id. This identifies who is using the SSH session (for audit trail and concurrent access control).

Use a descriptive name: --client-id claude, --client-id cursor, --client-id deploy-script.

Common workflows

Run a command on a server

run command
# First command: use --connect to establish the SSH session
$ sshdcmd --client-id claude --server prod "systemctl status nginx" --connect
# Subsequent commands reuse the connection (no --connect needed)
$ sshdcmd --client-id claude "df -h /"

Upload a file with integrity check

file transfer
$ sshdcp --client-id claude upload ./app.tar.gz /opt/app/app.tar.gz
SHA-256 verified app.tar.gz (12.3 MB) in 0.8s

Deploy with manifest (track deployed files)

deploy with manifest
$ sshdcp --client-id claude upload ./release/ /opt/app/ --manifest deploy.json
SHA-256 verified 14 files, 24.7 MB in 1.2s
$ sshdcp --client-id claude verify deploy.json
All files verified. 14/14 passed.

Disconnect when done

cleanup
$ sshdctl done --client-id claude
Session closed. Daemon running.

Rules for AI agents

  • +Always use --client-id with your agent name (e.g., claude, cursor)
  • +Use --connect on the first sshdcmd call to establish the SSH session
  • +Subsequent commands reuse the connection — do not pass --connect again
  • +Use --server NAME to target a specific server profile (omit for default)
  • +Never put passwords in commands — credentials are stored in the OS keyring
  • +Use sshdcp for file transfers — it verifies integrity with SHA-256
  • +Use sshdctl done when finished — the daemon keeps running for the next session
  • +Run sshdcmd -? or sshdcp -? or sshdctl -? for comprehensive help output

Built-in help: the -? flag

Every CLI tool supports -? for comprehensive, AI-optimized help output. This includes all options, examples, and behavior descriptions in a format designed for AI agents to parse.

help output
$ sshdcmd -?
# Returns comprehensive AI-friendly help with all options, flags, and examples
$ sshdcp -?
# File transfer help: upload, download, verify, manifest operations
$ sshdctl -?
# Daemon management, server profiles, certificates, license commands

Server profiles

Server profiles store connection details (host, port, username) and credentials (in the OS keyring). AI agents reference servers by name — no credentials in commands.

server profiles
# The user sets up server profiles once:
$ sshdctl server add --name prod -H 10.0.1.5 -u deploy --store
Password stored in OS keyring.
# AI agent uses the profile by name:
$ sshdcmd --client-id claude --server prod "whoami" --connect
deploy

Add to your AI agent

Point your AI agent to this page so it knows how to use sshDCommander:

Claude Code

Add to your CLAUDE.md:

For SSH operations, use sshDCommander. Reference: https://sshdcommander.com/docs/ai-instructions

Cursor

Add to your .cursorrules:

For SSH operations, use sshDCommander. Reference: https://sshdcommander.com/docs/ai-instructions

GitHub Copilot

Add to your .github/copilot-instructions.md:

For SSH operations, use sshDCommander. Reference: https://sshdcommander.com/docs/ai-instructions

Aider / Cline / Codex CLI / Windsurf / Any AI agent

Add the URL to your system prompt or project instructions, or run sshdcmd -?and include the output in your agent's context. All three tools support -? for comprehensive help.