# Docs


- **Get started**
- [Introduction](/docs): Docs for vmup: install the CLI, upload a batch over SSH, and paste the prompt into your coding agent.
- [Install](/docs/install): Install the vmup CLI with npm, pnpm, yarn, bun, or the curl script. Needs Node 18+ and OpenSSH, then you are ready for the first upload.
- [First upload](/docs/quickstart): Walk through install, vmup init, an SSH check, one file upload, and pasting the prompt into the agent.

- **How-to**
- [Run init again](/docs/guides/init): Run vmup init to add a profile, overwrite one, or write config.toml without the wizard. Use -y and VMUP_* when you cannot answer prompts.
- [Upload files](/docs/guides/upload): Pass paths, drop a directory, or use the native picker. Every mode uploads over SSH into one remote folder and copies the prompt for the agent.
- [Capture the clipboard](/docs/guides/clipboard): How vmup --clip captures copied files and screenshots, batches them over SSH, and copies a prompt to paste into the agent.
- [Upload screenshots to a remote coding agent](/docs/guides/screenshots-to-agent): Send laptop screenshots to an agent on a VM: capture with --clip or watch a folder, upload over SSH, paste the prompt.
- [Clipboard to SSH for Claude Code or Cursor](/docs/guides/clipboard-for-agents): Use vmup --clip to batch clipboard files over SSH and paste the prompt into Claude Code, Cursor, or any agent that reads paths on the host.
- [Watch a folder](/docs/guides/watch): Watch a folder for files added after start, press Enter to upload one SSH batch, and paste the prompt into the coding agent.
- [Point vmup at another VM](/docs/guides/profiles): Point vmup at another host with saved profiles, a default profile, or a one-shot ssh_host alias from your OpenSSH config.
- [Restrict to images](/docs/guides/restrict-types): Turn off accept_all_files for images only, then opt into video with --video or extra types with --force on picker and path args.
- [Script vmup](/docs/guides/scripting): Non-interactive vmup init, VMUP_* env overlays, and --json on stdout for scripts and CI. The spinner still goes to stderr.
- [Clean up batches](/docs/guides/cleanup): TTL, the remote sweeper cron, vmup prune --all to wipe live batches, and leftover local staging under ~/.cache/vmup after a failed or kept upload.
- [Fix SSH](/docs/guides/ssh): Read the printed SSH error, match it to a cause (key, host, permissions), then retry with vmup check before you upload.

- **Reference**
- [Commands](/docs/reference/commands): Reference for vmup, init, check, profiles, watch, prune, and the default upload, including what each command is for.
- [Flags](/docs/reference/flags): Every vmup command-line flag, which commands accept it, and how upload, watch, clip, and prune options differ.
- [config.toml](/docs/reference/config): config.toml path, keys, defaults, and profiles for hosts, TTL, file limits, and SSH settings.
- [Environment variables](/docs/reference/env): Set VMUP_HOST, TTL, and other keys as environment overlays so scripts can change SSH and limits without editing config.toml.
- [File types and limits](/docs/reference/file-types): Allowed extensions, size and count caps, junk names vmup drops, and staged names like image-01.png on the remote host.
- [JSON output](/docs/reference/json): JSON stdout schema for vmup --json on upload and check, including fields for batch id, remote path, and prompt.
- [Exit codes](/docs/reference/exit-codes): What vmup exit codes 0, 1, 2, 3, 4, and 130 mean, and which failures (usage, empty batch, SSH, upload, cancel) map to each.
- [Error strings](/docs/reference/errors): Messages the CLI prints, which code path emits them, and what to do next when SSH, staging, or an empty batch fails.

- **Explanation**
- [How a batch is built](/docs/explain/how-it-works): Collect files, stage them under a batch id, stream them over ssh into a partial remote dir, rename into place, and copy the prompt to the clipboard.
- [Why batches expire](/docs/explain/ttl): TTL is in minutes. The host cron deletes expired batches. vmup prune --all deletes every remote batch now. The laptop sleep job is a backup if the VM was unreachable.
- [Direct SSH vs ssh_host](/docs/explain/ssh-modes): Choose direct SSH (host, user, key, port) or an OpenSSH alias (ssh_host) from ~/.ssh/config. vmup still calls ssh.
- [vmup vs scp and rsync](/docs/explain/vs-scp): When to use vmup instead of copying one file with scp or syncing a tree with rsync, if the job is one folder path for a coding agent.

- **Project**
- [Changelog](/docs/changelog): Release notes for vmup, from 0.1.0 through the current npm version, covering CLI, TTL, install, and docs-site changes.
- [Security and contact](/docs/contact): Report CLI bugs on GitHub, send security issues through the private advisory form, and find source, npm, and the MIT license.

# Learn

> How to get screenshots, PDFs, and other laptop files onto the VM where Claude Code, Cursor, or Codex runs. Paste fails over SSH; a remote path does not.

- [Guides for remote coding agents](https://vmup.dev/learn): How to get screenshots, PDFs, and other laptop files onto the VM where Claude Code, Cursor, or Codex runs. Paste fails over SSH; a remote path does not.
- [How to paste an image into Claude Code over SSH](https://vmup.dev/learn/claude-code-paste-image-ssh): Ctrl+V cannot paste a laptop screenshot into Claude Code over SSH. Copy the PNG onto the remote host, then give Claude the file path. Four methods that work.
- [Send laptop files to a coding agent on a remote VM](https://vmup.dev/learn/send-files-to-remote-coding-agent): A remote coding agent reads paths on the VM. Screenshots, PDFs, and recordings on your laptop stay invisible until you copy them over SSH into one folder.
- [Cursor Remote-SSH cannot analyze local files](https://vmup.dev/learn/cursor-remote-ssh-local-files): Cursor cannot analyze local files over Remote-SSH. A Windows or Mac path in chat is a dead link. Upload the file to the host, then attach the remote path.
- [Claude Code SSH screenshot tools compared](https://vmup.dev/learn/claude-code-ssh-screenshot-tools): clipaste vs clipssh vs cssh for Claude Code over SSH, plus scp, Invoke, and vmup. Pick a shim, a path uploader, or a batch copy. Updated September 2026.
- [Claude Code: no image found in clipboard over SSH](https://vmup.dev/learn/claude-code-no-image-found-clipboard-ssh): Claude Code says no image found in clipboard over SSH. The remote clipboard is empty. Diagnose tmux, WSL, and Ctrl+V, then scp the PNG and pass that path.

## Optional

- [Full docs and Learn guides as markdown](https://vmup.dev/llms-full.txt)