Getting a file into a virtual machine, when Proxmox has no file manager

You have a file on your own computer and it needs to be inside a guest. You look through the interface for an upload button pointing that way, and there is not one.

That absence is a design decision, not an oversight, and understanding why makes the rest of this obvious. Proxmox VE manages the machine, not the inside of the machine. From the outside a guest's storage is a disk image: a large opaque blob. The hypervisor does not read the filesystem in it, which is precisely why it can host any operating system without knowing anything about it.

So every way in is a way of crossing that boundary on purpose, and each one crosses it differently.

The boring answer that is usually the right one

Copy it over the network, the same way you would to any other machine. A file copy over SSH, a file share, an object store, a web download from inside the guest.

This gets skipped surprisingly often because it feels too ordinary, as though virtualisation ought to offer something better. It does not, and it should not. The guest is a machine on your network; treat it like one. This path handles any size, keeps its own permissions, and does not involve the hypervisor at all.

For a Linux guest with SSH, the shortest reproducible path is:

# local computer -> guest
scp ./config.yaml admin@192.0.2.50:/tmp/config.yaml

# guest -> local computer
scp admin@192.0.2.50:/var/log/app.log ./app.log

Use an account that can write only where it needs to, copy into a temporary location first, and then move the file into place from inside the guest. For anything important, compare a checksum at both ends:

sha256sum ./config.yaml
ssh admin@192.0.2.50 'sha256sum /tmp/config.yaml'

Matching hashes are the success condition. A completed progress bar only proves that the transfer ended, not that you copied the intended file to the intended machine.

The cases below are for when this one is not available.

When the guest is unreachable but running

The guest agent gives you a channel that does not use the network, because it runs over a virtual device between host and guest.

It genuinely can read and write files. The two operations exist as their own endpoints, and they are exactly what you want for dropping a configuration file or a key into a machine that has lost its network.

The limit worth knowing before you rely on it: Proxmox's guest-agent file-write API caps one request at about 60 KiB. This channel was built for small, ad-hoc operations. It is excellent for a config file and the wrong path for an installer image, and finding that out mid-incident is worse than reading it here.

Before depending on that route, prove the channel from the Proxmox host:

qm agent <VMID> ping

A successful ping proves that the agent is answering; it does not prove that a later file operation used the correct path or permissions. Check the resulting file from inside the guest. If the command times out, fix the guest agent rather than treating it as a bulk-transfer fallback.

When the guest is off

With the guest stopped, its disk image can be mounted on the host and its filesystem browsed directly. This is the most powerful option: full access, any size, no agent needed.

It also has the sharpest edge in this article.

There is no single safe mount command because the procedure changes with the storage backend, partition table, encryption and LVM inside the guest. Take a backup first, confirm that the VM is fully stopped with qm status <VMID>, and use this as a recovery procedure rather than a routine upload method.

The shortcut that quietly destroys things

Do not mount a running guest's filesystem from the host.

It often appears to work. You mount the image, you see files, you copy one in, nothing complains. Meanwhile the guest also has that filesystem mounted and is caching its own idea of what is on disk. Two independent writers, one filesystem, neither aware of the other. The result is corruption that shows up later, looking like a disk problem rather than like something you did.

If the guest is running, use the network or the agent. If you need the disk, stop the guest first.

When the guest will not boot at all

This is the moment you most want a file out, and the previous options have all failed.

Take the route through a backup. Backups can be inspected and individual files retrieved from them without restoring the whole guest. It is slower than everything else here, and it is the only path that still works when the machine itself is unusable.

Worth noticing: this is another reason a backup you have never opened is not yet a backup. The day you need a single file out of a dead machine is a bad day to discover the archive does not restore.

Containers are a different problem

A container does not have a disk image with an opaque filesystem inside. Its files sit on the host's own storage, so from the host they are simply there.

That asymmetry is why the container version of this question is its own separate search. Same task, completely different difficulty, and advice written for one is often wrong for the other.

Pick the path before you start

• Guest reachable and file is any size: use SSH, SFTP or a file share.
• Guest network broken, agent answering and file is small: use the guest-agent channel.
• Guest fully stopped and you are doing recovery: inspect the disk with a backup already available.
• Guest will not boot and you need data out: inspect a known-good backup.

The rollback for a bad configuration file is equally simple only if you prepared it: keep the original beside it, make one change, and do not remove the original until the service and the next reboot have both succeeded.

What Atlas does, and its limits

Atlas offers a file browser for a guest, and the design choice inside it is the part worth stating.

It runs inside the guest and listens only on the guest's own loopback address, so it is not reachable from your network at all. You reach it through Atlas. That means adding a file browser does not add a service exposed to anything else on the LAN, which is the usual quiet cost of putting a web file manager on a machine.

The limits, plainly: it is per guest and has to be present in the guest you want to browse; it is a convenience for looking and moving individual files, not a transfer mechanism for large data; and it does not replace backups. For bulk data the network path above is still the right answer, and for a machine that will not boot, the backup route is still the only one.