First upload
Walk through install, vmup init, an SSH check, one file upload, and pasting the remote folder path into the agent.
This lesson ends with a file on the remote host and a path on your clipboard. Work through it on a machine that can SSH to your VM.
1. Install vmup
Follow Install until vmup --version prints a version.
2. Create config
vmup initPress Enter to keep a value in [brackets].
On a first run, vmup asks:
| Prompt | Typical answer |
|---|---|
| Profile name | default |
| Host | IP or DNS of the VM. Enter skips; you cannot upload until a host exists. |
| SSH user | ubuntu unless your image uses something else |
| SSH key path | ~/.ssh/id_ed25519 if that file exists, otherwise ~/.ssh/id_rsa |
| SSH port | 22 |
| Remote dir | ~/vmup |
| TTL minutes | 5 |
| Screenshots / watch folder | macOS: ~/Desktop. Linux: ~/Pictures/Screenshots |
| Accept all file types | Y (PDFs, video, anything). n is images only. |
| Install remote cleanup sweeper | Y |
vmup writes ~/.config/vmup/config.toml, then tests SSH and installs ~/vmup/.cleanup.sh on the host (cron every minute) if you said yes.
If the VM is off, config is still saved. You will see SSH setup incomplete and a pointer to vmup check.
Non-interactive setup: VMUP_HOST=… vmup init -y. See Script vmup.
3. Confirm SSH
vmup checkSuccess looks like:
SSH OK default ubuntu@192.168.1.10
Remote dir: ~/vmup
Sweeper: installedIf the sweeper is missing:
Sweeper: missing
Reinstall: vmup check --sweeperFix connection failures in Fix SSH.
4. Upload one file
vmup ./shot.pngReplace ./shot.png with a file you have. PDF, video, and other types work while accept_all_files is true (the default).
A TTY shows a spinner on stderr:
⠋ Checking SSH…
⠋ Uploading 1 file 240.0 KB / 240.0 KB 2sThen stdout:
Uploaded 1 file → default
Agent folder: ~/vmup/agents-20260911-140128-a1b2c3d4-e5f6-7890-abcd-ef1234567890/
Prompt:
Please inspect all files in ~/vmup/agents-20260911-140128-a1b2c3d4-e5f6-7890-abcd-ef1234567890/stderr adds (copied agent folder path to clipboard) when pbcopy (macOS), wl-copy, or xclip works.
The remote file is renamed to image-01.png (or file-01.pdf, video-01.mov) inside that folder. How a batch is built explains why.
5. Give the path to the agent
Paste into the agent. The clipboard already holds the folder path. The printed prompt is the sentence most agents need:
Please inspect all files in ~/vmup/agents-…/You stay in the same thread. The agent opens that directory on the VM.
If something failed
| What you saw | What to do |
|---|---|
Profile "default" has no host | Run vmup init and fill in Host, or set VMUP_HOST. |
SSH key not found | The key path in config is wrong. |
permissions are too open | chmod 600 on the private key. |
No files to upload (exit 2) | The path did not exist, or the file was skipped. |
SSH preflight failed + Local staging kept: … | SSH died after staging. Fix the host, then retry. Staging stays under ~/.cache/vmup/. |
Next
- Upload files for the picker and directories
- Clipboard loop and Watch a folder
- Commands for the full catalog