Give AI agents SSH access without sharing passwords

How AI agents use your SSH servers without your passwords

AI coding agents such as Claude Code, Codex or Cursor are good at server work: reading logs, checking services, deploying a build. Giving them your SSH password or private key is not. With Agent Access, the running NixSCP application keeps the credentials and makes the SSH connection itself. The agent only runs the nixscp command (or uses the MCP server) and gets the output and exit code back.

1. You switch a site on in NixSCP and choose what agents may do there.
2. The agent runs a command such as nixscp --connect web1 --cmd "df -h".
3. NixSCP checks and connects. The request travels over a local socket only your user account can open. NixSCP checks the site's permissions and rules, asks you first if the site is set to ask, logs the request, connects with the stored credentials and streams the result back.

Passwords, private keys and key passphrases are never printed, written to files or handed to the agent.

Requirements

• NixSCP is running (and unlocked, if you use the NixSCP Pro password).
• Saved passwords are encrypted: a master password (Preferences › Security), or the NixSCP password of NixSCP Pro, which encrypts the whole configuration. Without either, NixSCP refuses all agent requests, because any program could decode merely obfuscated passwords.
• SFTP or SCP sites only.
• A known host key. Connect to the site once in NixSCP and accept its key. Agent requests refuse unknown and changed host keys.
• No interactive sign-in. A stored password or a key. If the key has a passphrase, NixSCP asks you for it in its own window; the passphrase stays in NixSCP.

Protect private key files with a passphrase: any program you run can read an unprotected key file directly. The Agent Access dialog warns you about it.

Set up a site

1. In the Login dialog (Site Manager), select a saved SFTP or SCP site and click Edit.
2. Click Agent Access..., to the left of Advanced....
3. Choose Off, Allowed without asking or Ask me each time.
4. Tick the permissions, and optionally set a name for agents and command rules.
5. Click OK and save the site.

Permissions

Everything is on by default once you switch a site on. Download files without Upload files makes the site download-only.

Approval: ask me each time

With Ask me each time, NixSCP shows every request in a window that stays on top: the site, and the command, file, tunnel or shell requested. The agent waits for your answer:

• Allow once: this request only.
• 1 hour or 24 hours: this request, and all requests for the site for that time without asking (until NixSCP exits).
• Always: switches the site to Allowed without asking (saved and logged).
• Deny: the agent gets exit code 255 and "The user denied the request in NixSCP."

Hide real site names from agents

Agents normally see a site by its full name, folders included (Clients/Acme/web1). Set Name for agents to give it another name, for example web1: agents see and use only that name, and your folder and client names stay hidden. Host, user and port are still listed. Names must be unique among the sites agents may use.

Command rules: allow and deny lists

Optional patterns that limit the commands agents may run. Both lists empty means every command is allowed. One pattern per line; empty lines and lines starting with # are ignored.

• A pattern must match a whole command, case-sensitively. * matches any text (also spaces and /), ? one character, [a-z] one character of a set. So uptime allows only uptime, and systemctl status * allows systemctl status nginx but not systemctl restart nginx.
• The command line is split into simple commands at ; & && | || and new lines, outside quotes. cd /var/log && tail -n 50 syslog | grep error is checked as three parts.
• No part, and not the whole command, may match a denied pattern.
• With an allowed list, every part must match an allowed pattern, and command substitution ($(...), backticks) and output redirection to a file (>, >>, except to /dev/null) are refused. 2>&1 is fine.
• With any rules, interactive shells are refused, because typed input cannot be checked.

The Read-only preset fills in inspection commands (ls*, cat *, tail *, grep *, df*, ps *, systemctl status *, journalctl *, docker logs *, git log* and more), denies find actions such as -delete and -exec, and makes the site download-only.

Session recordings and audit log

• Recordings (on by default): each request with its command or file, output (up to 4 MB) and exit code. Commands › Agent Sessions... shows them. Encrypted with your NixSCP password when the configuration is encrypted. The newest 1000 from the last 90 days are kept.
• Audit log: every request, allowed or denied, with the reason. Commands › Agent Access Log.... A tab-separated file next to the configuration, readable by your user only; it never contains credentials or output.

Command line reference

nixscp --list [--json]                                  # sites agents may use
nixscp --connect <site> --cmd "<command>"               # run one command
nixscp --connect <site>                                 # interactive shell (needs a terminal)
nixscp --get <site> <remote-file> [<local-file-or-folder>]
nixscp --put <site> <local-file> [<remote-file-or-folder>]
nixscp --tunnel <site> <local-port>:<host>:<port>      # or a saved tunnel's name
nixscp --mcp                                            # MCP server on stdin/stdout
nixscp --help                                           # instructions for people and agents

• Everything after --cmd is the command, so --cmd uname -a works too; --cmd="..." is the same.
• Commands run in the login shell on the server without a terminal: use non-interactive flags such as --no-pager, -y or top -bn1.
• --get and --put move single files; use tar through --connect for folders.
• Tunnels listen on 127.0.0.1 from port 1024 up and stay open until the command ends.

Exit codes

Examples

nixscp --list
nixscp --connect web1 --cmd "sudo systemctl status nginx --no-pager"
nixscp --connect web1 --cmd "tail -n 200 /var/log/nginx/error.log"
echo "hello" | nixscp --connect web1 --cmd "cat > /tmp/hello.txt"
nixscp --get web1 /etc/nginx/nginx.conf ./nginx.conf
nixscp --put web1 ./deploy.tar.gz /tmp/deploy.tar.gz
nixscp --connect web1 --cmd "tar czf - /var/www/site" > site.tar.gz
nixscp --tunnel db1 5433:localhost:5432 &   # then: psql -h 127.0.0.1 -p 5433

Tell your agent: "Use nixscp for my servers. Run nixscp --help, then nixscp --list."

Security model and its limits

• Protected: the stored password, private key and passphrase never reach the agent; only the sites you switch on are visible; every site has its own permissions, rules and approval; unknown or changed host keys are refused; every request is logged.
• Not protected: any program running as your user can use the sites you switched on, within their settings (use Ask me each time for sites that matter); what an allowed command does on the server; unprotected key files; malware on your computer; output and files the agent has received.
• Agent Access settings are personal: they are never shared through Teams, and a session URL cannot set them.

Questions or problems? See the FAQ, open an issue on GitHub or write to hello@codewizdev.com.