Skip to content

SSH

The SSH feature grants the agent container access to a remote machine over SSH. It mounts your credentials into the container and injects connection instructions into the agent's system prompt so the agent knows the host is available and how to reach it.

Example

# Connect by IP
agentfile run --ssh [email protected] --ssh-key ~/.ssh/id_ed25519

# Connect by hostname
agentfile run --ssh [email protected] --ssh-key ~/.ssh/id_ed25519

--ssh-key is required when --ssh is set and supports ~ expansion.

Flags

Flag Description
--ssh Remote machine to connect to, in user@host format
--ssh-key Path to the SSH private key on the host

Notes

  • user@host format is required — bare hostnames without a user are rejected.
  • mDNS resolution (.local hostnames) requires the host to be reachable on the local network and responding to multicast DNS queries.
How it works

When --ssh is set, agentfile run performs the following before launching the container:

  1. Resolves the target host — plain IP addresses are used as-is; .local hostnames are resolved via mDNS (multicast DNS); all other hostnames are resolved via the system DNS resolver.

  2. Mounts the private key — the key file is mounted read-only into the container at /root/.ssh/<keyname>.

  3. Writes an ephemeral SSH client config — a temporary config is generated with the resolved IP, username, key path, and StrictHostKeyChecking no. It is mounted read-only at /root/.ssh/config and removed when the container exits.

  4. Adds a host entry — for hostname targets, an --add-host entry is injected so the container can resolve the hostname to the pre-resolved IP without relying on the container's DNS.

  5. Injects prompt instructions — the agent is told the host is available, its resolved IP, and the SSH command to connect.