explain

Agent vs SSH

When grain uses the guest agent, when it falls back to SSH, and why both exist.

Roles

Path	Strengths	Weaknesses
Guest agent	Structured API, streaming exec, fs/cp, health probes, PTY shell	Must be present (baked or deployed); Linux guest binary
SSH	Universal, interactive muscle memory, bootstrap agent deploy	Host-key noise, scp quirks, harder to automate cleanly

Default CLI behavior

Command	Prefers	Override
`grain x`	Agent streaming exec	`--ssh` / `--agent`
`grain sh`	Agent WebSocket PTY	`--ssh` / `--agent`
`grain cp`	Agent Put/Get	`--ssh` / `--agent`
`grain fs`	Agent only	—
Create deploy	SSH used to install agent when missing	Golden images skip deploy when healthy

Create wait modes

Mode	Ready when
`auto`	Agent if image HasAgent, else SSH
`ssh`	SSH accepts; agent soft-deployed
`agent`	Agent health required (hard fail)
`userdata`	Agent + userdata marker

Transport

Host → agent:

TCP hostfwd to guest :7475 (always available with QEMU user net)
virtio-vsock when agent_transport allows and /dev/vhost-vsock exists (typically Linux)

Practical guidance

Day-to-day automation: agent (x, cp, fs, API exec)
Debugging a broken agent: grain sh --ssh and grain logs
Images: prefer grain-ubuntu so agent is already present
Security-sensitive tokens: prefer egress proxy over writing secrets into the guest when possible