= VM File Access
:page-parent: Using Spectrum
:page-nav_order: 1

// SPDX-FileCopyrightText: 2024-2025 Alyssa Ross <hi@alyssa.is>
// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0

Spectrum VMs start without any access to user data, and with all
application state being discarded when the VM exits, but these
restrictions can be softened at runtime as required.

== Persistent application data

To make an application VM persistent, run, for example,
`vm-set-persist gGKghi configured`, where "gGKghi" is the VM's ID (can
be found using xref:running-vms.adoc#basic-vm-commands[`lsvm`]) and
"configured" is the name to be given to this persistent application
instance.  The VM's home directory will now be saved under the given
name.  For now, names are scoped to only to a user data partition, not
to an application, so you cannot create instances of different
applications with the same name.

Then, to start a VM with that persistent data in future, give the
instance name to `run-appimage` or `run-flatpak` as an extra argument.
This run of the application will also persist further changes to its
home directory under the same name.

Persistent application data is stored as directories prefixed with
"persist." under Spectrum/data/spectrum/storage on the user data
partition.  They can be manually renamed, and, as long as they are not
being used by a currently running VM, removed.

For manually configured VMs, persistence can optionally be enabled
when the VM is imported, by providing the storage location as an extra
argument to `vm-import`.  The name of each imported VM will be used as
its instance name.

== File chooser portal

Some applications implement the
https://flatpak.github.io/xdg-desktop-portal/[XDG Desktop Portal]
https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.FileChooser.html[File
Chooser API].  If you're using an application that does, when you
choose to open or save a file in the application, you'll see a file
chooser dialog that allows you to choose a single location to open or
save to.  The host will then share this single location with the VM.

TIP: Some applications will only try to use portals when they detect
that they're running in a sandbox, and they won't realize that a
Spectrum VMs is a sandbox.  There might be ways to force them to use
portals anyway, for example by setting the environment variable
`GTK_USE_PORTAL` to `1` for GTK 3, or
https://docs.gtk.org/gtk4/running.html#gdk_debug[`GDK_DEBUG`] to
`portals` for GTK 4.

TIP: Downloads to a fixed directory will not use the portal, and so
will not be visible outside the VM.  For example, a normal download in
Firefox will just download the "Downloads" directory on the transient
VM filesystem, but downloading a file using "Save Link As…" will use
the portal.

== Manually sharing files with a VM

When using an application that doesn't implement the File Chooser API,
you can still give it access to files manually.  Each VM has
xref:creating-custom-vms.adoc#filesystem[access] to the /run/fs/_VM
ID_ directory on the host (mounted at /host in the default Spectrum VM
image).  For the VM, this directory is read-only, but writeable files
and directories can be bind-mounted into it:

[example]
====
1. Create a file to share with the VM:
+
[listing]
[source,shell]
echo "Hello, world!" > /media/4e43cdc2-82b2-4d94-8a90-b6c6189312d2/example.txt

2. Create an empty file to bind mount over:
+
[listing]
[source,shell]
touch /run/fs/gGKghi/example.txt

3. Create the bind mount:
+
[listing]
[source,shell]
mount --rbind /media/4e43cdc2-82b2-4d94-8a90-b6c6189312d2/example.txt /run/fs/gGKghi/example.txt
====