Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.rafftechnologies.com/llms.txt

Use this file to discover all available pages before exploring further.

Updated May 8, 2026 There’s nothing Raff-specific about file transfer — every method below uses your existing SSH credentials and VM IP. If you can SSH into the VM, you can transfer files to it. Pick the tool that fits the job:
JobTool
Copy one file or a small directory, one-shotscp
Browse files interactively, mix uploads/downloads in one sessionsftp or a GUI client
Sync a large directory, resume after interruption, copy only changed filesrsync
Drag-and-drop GUI on macOS / Linux / WindowsFileZilla
Drag-and-drop GUI on Windows specificallyWinSCP
All five use the standard SSH/SFTP protocol on TCP port 22 of the VM’s public IPv4. If your VM is in a VPC without a public IP, transfer through the Platform Router’s port forwarding or a bastion VM.

​
Before you start

  • A VM with a public IPv4 (or a port-forwarded VPC route)
  • An SSH key on your local machine, or the password you set with Reset password
  • The VM’s public IP — copy it from the VM detail page
Throughout this page, examples use:
  • 1.2.3.4 — placeholder for your VM’s public IPv4
  • root — the default Linux user; substitute your sudo user if you’ve changed it
  • ~/.ssh/id_ed25519 — your SSH private key path on your local machine

​
SCP — one-shot file copy

scp (secure copy) is the simplest tool — one command, copies one file or one directory, then exits.

​
Upload — local → VM

# Single file
scp -i ~/.ssh/id_ed25519 ./local-file.tar.gz root@1.2.3.4:/root/

# Directory (recursive)
scp -i ~/.ssh/id_ed25519 -r ./local-dir root@1.2.3.4:/var/www/

# Rename on the way
scp -i ~/.ssh/id_ed25519 ./config.yml root@1.2.3.4:/etc/myapp/config.yml

​
Download — VM → local

# Single file
scp -i ~/.ssh/id_ed25519 root@1.2.3.4:/var/log/app.log ./

# Directory
scp -i ~/.ssh/id_ed25519 -r root@1.2.3.4:/var/backups ./

​
Common flags

FlagWhat it does
-i <path>Use this SSH private key
-rRecursive (required for directories)
-P <port>Use a non-default SSH port — typical when you’re going through a Platform Router port-forward (-P 2222)
-pPreserve modification times, access times, and modes
-CCompression — useful on slow links, marginal on fast ones
-qQuiet — suppress progress meter
-vVerbose — useful when debugging “permission denied” or “no route to host”

​
When to skip SCP

  • Big directory trees — scp -r doesn’t resume on interruption. Use rsync instead.
  • Many small files — scp opens a separate transfer per file. rsync or a tar-pipe is much faster.
  • Files larger than a few GB — scp works but has no progress / resume. Use rsync --progress instead.

​
SFTP — interactive session

sftp opens a long-lived FTP-like session over SSH. Useful for browsing and ad-hoc up/downloads in one connection. 
sftp -i ~/.ssh/id_ed25519 root@1.2.3.4
Inside the session, common commands:
CommandWhat it does
ls / ls -laList files on the remote VM
llsList files locally (note the leading l)
cd /var/wwwChange directory on the remote
lcd ./local-dirChange directory locally
pwd / lpwdShow current remote / local directory
get file.tar.gzDownload to the current local directory
put file.tar.gzUpload to the current remote directory
mget *.logDownload all files matching a glob
mput *.pngUpload all matching local files
rm, mkdir, renameStandard remote file ops
bye or exitEnd the session
A typical workflow: cd into the right remote dir, lcd to the local source, then put / get until you’re done — far faster than re-running scp for each file.

​
rsync — sync directories, resume on failure

rsync is the right tool for anything bigger than “a couple of files”. It only transfers changed bytes, resumes interrupted runs, optionally compresses on the wire, and handles permissions correctly.

​
Basic syntax

# Upload — local dir → VM (sync, don't delete remote)
rsync -avz -e "ssh -i ~/.ssh/id_ed25519" ./local-dir/ root@1.2.3.4:/var/www/

# Download — VM dir → local
rsync -avz -e "ssh -i ~/.ssh/id_ed25519" root@1.2.3.4:/var/log/ ./logs/
The trailing / on local-dir/ matters: with the slash, it copies the contents into /var/www/; without it, it copies the directory itself as /var/www/local-dir/. Same convention applies to remote paths.

​
Useful flags

FlagWhat it does
-aArchive mode — recursive + preserves permissions, times, symlinks, ownership
-vVerbose — show what’s being transferred
-zCompress in flight — helpful on slow / high-latency links
-PShow progress + enable resume of partially-transferred files
--dry-run / -nShow what would change without actually doing it
--deleteDelete remote files that no longer exist locally — make remote a mirror
--exclude=<pattern>Skip files matching the pattern (e.g. --exclude='node_modules')
--bwlimit=<KB/s>Cap bandwidth — useful when transferring during business hours

​
Resume-after-failure pattern

If a long rsync dies mid-transfer (network blip, laptop closed, SSH timeout), just run the same command again — rsync figures out what’s already there and only transfers the rest. With -P it picks up partial files at the byte level. 
rsync -avzP -e "ssh -i ~/.ssh/id_ed25519" ./big-tree/ root@1.2.3.4:/data/

​
When you’d use a tar-pipe instead

For one-shot transfer of a huge tree of small files, a tar-pipe can outperform rsync because it avoids the per-file roundtrips: 
tar -czf - ./local-dir | ssh -i ~/.ssh/id_ed25519 root@1.2.3.4 "tar -xzf - -C /target"
Use this when you’re copying once (initial seed), and use rsync when you’ll re-sync.

​
FileZilla — cross-platform GUI

FileZilla runs on macOS, Windows, and Linux. Drag-and-drop with the same SSH credentials.

​
Add a connection profile

  1. File → Site Manager → New Site
  2. Fill in:
    • Protocol: SFTP – SSH File Transfer Protocol
    • Host: 1.2.3.4 (your VM’s public IP)
    • Port: 22 (or your port-forward, e.g. 2222)
    • Logon Type: Key file
    • User: root (or your sudo user)
    • Key file: browse to ~/.ssh/id_ed25519 (the private key)
  3. Connect
The first connection prompts to trust the VM’s host fingerprint — accept it; it’s recorded for future sessions.

​
Day-to-day use

The split-pane shows your local files on the left, the VM’s files on the right. Drag-and-drop in either direction starts a transfer; the queue at the bottom shows progress. Tools → Speed limits lets you cap bandwidth.

​
WinSCP — Windows-only GUI

WinSCP is the established Windows file-transfer client — same idea as FileZilla but with a more Explorer-like UI.

​
Add a session

  1. Session → New Session
  2. File protocol: SFTP
  3. Host name: your VM’s public IP
  4. Port number: 22
  5. User name: root
  6. Advanced → SSH → Authentication → Private key file: select your .ppk file (WinSCP needs a PuTTY-format key)
    • If you have an OpenSSH-format key, WinSCP prompts to convert it on first use, or use puttygen to convert manually
  7. Login
The first connection prompts to trust the host key — accept it.

​
Day-to-day use

Same Explorer-style interface as FileZilla. Drag-and-drop, browse remote / local in parallel, queue multiple transfers. WinSCP also has a built-in text editor for editing remote config files in place.

​
Quick reference — which tool when

GoalBest tool
Push a single config filescp
Pull a single logscp
Browse the VM’s filesystem and grab a few thingssftp or FileZilla / WinSCP
Copy a big directory the first timersync -avzP (or tar pipe for many small files)
Keep two directories syncedrsync -avz --delete on a cron / before each deploy
Edit a remote config file in placeWinSCP’s built-in editor, or nano / vim over SSH
Move a database dumprsync for resume capability + --bwlimit to avoid saturating the link

​
Common issues

SSH refused your key. Causes:
  • Wrong key path (-i ~/.ssh/id_ed25519 vs the one you actually authorized on the VM)
  • Wrong username (root vs your sudo user)
  • Key permissions too open — chmod 600 ~/.ssh/id_ed25519 on macOS/Linux
  • The public key isn’t in ~/.ssh/authorized_keys on the VM — see Connect via SSH
The VM isn’t reachable on port 22:
  • Confirm the VM is active (not paused or stopped) on the dashboard
  • Confirm the IP is correct — VMs that lose their auto-assigned public IP get a different one when re-attached
  • Check the Firewall — if you’ve attached a custom group, verify TCP 22 is allowed inbound from your IP
  • Test with ssh -v root@1.2.3.4 first; if SSH times out too, the issue is networking, not file transfer
Several knobs to try:
  • Add -z (rsync) or -C (scp) for compression on text-heavy files; for already-compressed binaries (.gz, .zip, .mp4), compression slows things down
  • Use rsync -avP instead of scp -r — rsync’s per-file overhead is much lower
  • Check if the bottleneck is your local upload, not the VM (speedtest-cli)
  • For huge files, split-and-parallel: split -b 1G big.tar.gz part- then rsync the parts
scp and sftp reset to default umask permissions; rsync -a preserves them. Use rsync with -a if perms matter (executable scripts, key files, etc.). After upload, you can fix in the guest with chmod / chown.
Likely a broken symlink in the source tree. Either fix the source (delete the dangling symlink) or switch to rsync — rsync -a follows symlinks correctly with -L, or copies them as symlinks with -l.
Use df -h over SSH first to confirm there’s enough free space. For VMs running tight on disk, attach a Volume and transfer to the volume mount point instead.

Connect via SSH

The same credentials and IP that file transfer uses.

Authentication

SSH keys vs passwords, generating and adding keys.

Volumes

Attach extra disk capacity for big file transfers.
Last modified on May 8, 2026