Deployment Methods

Deployment Methods and OverlayFS

English · Deutsch · Français · Español · Italiano · Português · Русский

Anvil can deploy mods in two ways. The selection is stored per game instance under Settings → Expert → Mod deployment.

Comparison

	Symlinks (default)	OverlayFS (experimental)
Game directory	Anvil creates links to mod files	The unchanged game directory is covered by a mod layer
System privileges	Not required	Required to mount and unmount
Launch paths	Through Anvil; direct Steam launch with permanent deployment	Any launch path while the layer is mounted
Game writes	Go to the normal game directory	Go to the configured overwrite directory
Cleanup	Links are removed after the game exits	Kernel mount and temporary stage are removed after the game exits
“Keep mods in the game directory permanently”	Available	Hidden and always disabled

Symlinks

Symlinks are the default. Anvil creates links in the game directory for active mod files. File conflicts follow the order in the mod list: a mod higher in the list has higher priority.

After a normally monitored game session, Anvil removes the links again. The original mod storage is not changed.

Keep mods in the game directory permanently

This option is available only for symlinks. When enabled, the links remain after the game and Anvil close. The game can then start modded directly through Steam or another launcher.

Important details:

• The option applies only to the current game instance.
• Anvil turns it off when switching to another instance.
• A game update or “verify files” can replace or remove links. Deploy again through Anvil afterwards.
• Do not move or delete Anvil's data directory while links are deployed.
• Turn the option off before starting the game without mods.

OverlayFS

OverlayFS is a Linux kernel feature. Anvil mounts a merged view directly on the configured game directory:

visible game directory
├─ mod stage from the active profile
├─ original game directory
└─ runtime writes → overwrite directory

The original game files are not replaced. While the mount is active, Steam, Proton and the game see the merged view. This makes every launch path work, including a direct Steam launch.

Lifecycle

1. Anvil reads the profile, mod order and game-specific deployment rules.
2. It builds a new stage from the active mods.
3. It mounts the layer on the game directory before launching the game.
4. Game writes go to the configured overwrite directory.
5. Only after the real game process exits does Anvil unmount OverlayFS and remove the temporary stage.

“Keep mods in the game directory permanently” is hidden for OverlayFS and saved as false. A global kernel mount must not survive unnoticed as stale permanent state.

Why is a password required?

Mounting and unmounting a kernel filesystem requires system privileges on Linux. The password prompt belongs to pkexec/polkit, not to Anvil. Anvil never stores the password.

Without additional setup, the system asks for authorization when deploying. “Set up password-free mounting …” performs a one-time installation of:

• the root-owned helper /usr/local/libexec/anvil-overlay-mount;
• a polkit rule for the current Linux user.

Afterwards, exactly that fixed helper may run without another password prompt. Anvil deliberately does not authorize a user-writable script.

Requirements

OverlayFS is available only when the runtime checks pass:

• The running kernel supports OverlayFS or provides a loadable overlay module.
• pkexec/polkit is installed.
• The game and instance paths are accessible.
• The overwrite directory is on a supported Linux filesystem such as ext4, btrfs or xfs.

If a requirement is missing, Anvil keeps the stored selection but disables the Overlay choice and displays the reason. Symlinks remain the safe default.

OverlayFS is not available when Anvil itself runs as a Flatpak — the sandbox cannot reach pkexec on the host. For OverlayFS, use the AppImage or a native installation.

Safety and troubleshooting

• Run game updates and Steam file verification only while OverlayFS is unmounted.
• Never modify the stage, work directory or overwrite directory while the mount is active.
• If the game did not close cleanly, first check for remaining game or launcher processes.
• If password prompts continue after setup, check the polkit setup again in the Expert tab.
• If Anvil reports an unsupported filesystem, move the overwrite location to ext4, btrfs or xfs.
• Switch back to symlinks if needed. Anvil unmounts an existing overlay before changing methods.

OverlayFS is deliberately opt-in. Existing instances remain on symlinks until the user explicitly selects OverlayFS.