Mounts

airlock can share host files and directories into the VM using VirtioFS mounts. The project directory is always mounted automatically at its exact host path, but you can add additional mounts for things like SSH config, credential files, or shared caches.

Defining a mount

Each mount is a named entry under [mounts]:

[mounts.ssh-config]
source = "~/.ssh/config"
target = "~/.ssh/config"
read_only = true

The source is a path on the host and target is the path inside the container. Both support ~ expansion to the respective home directory.

Container-side `~` and `HOME`

The default home directory inside the sandbox comes from the OCI image’s user record — typically /root for images that run as root. If you override HOME via [env], ~ in mount targets expands to your value instead, so the path the file is mounted at matches what $HOME/... resolves to inside the shell:

[env]
HOME = "/home/dev"

[mounts.ssh-config]
source = "~/.ssh/config"   # host: ~/.ssh/config (your host home)
target = "~/.ssh/config"   # guest: /home/dev/.ssh/config

Without the override, the same target = "~/.ssh/config" would mount at /root/.ssh/config while the shell’s $HOME reported /root — either way, ~ and $HOME agree. The override is only needed when the image’s home doesn’t match where you actually want files to land (e.g. running as a non-root user the image doesn’t ship with).

Read-only mounts

Setting read_only = true prevents the container from writing to the mount. This is a good default for configuration files and credentials that the sandbox should be able to read but not modify:

[mounts.aws-credentials]
source = "~/.aws/credentials"
target = "~/.aws/credentials"
read_only = true

Handling missing sources

By default, airlock fails if a mount’s source path doesn’t exist on the host. The missing field controls this behaviour:

[mounts.optional-config]
source = "~/.config/myapp/settings.json"
target = "~/.config/myapp/settings.json"
missing = "warn"

The available options are:

fail (default) — stop with an error if the source doesn’t exist
warn — skip the mount and print a warning
ignore — skip the mount silently
create-dir — create the source as a directory and mount it
create-file — create the source as a file and mount it

When using create-file, you can provide initial content for the new file:

[mounts.git-config]
source = "~/.airlock/gitconfig"
target = "~/.gitconfig"
missing = "create-file"
file_content = "[user]\n\tname = Dev\n\temail = dev@example.com\n"

Disabling a mount

A mount can be temporarily disabled without removing it from the config. This is useful when a preset defines a mount that you don’t need:

[mounts.ssh-config]
enabled = false
source = "~/.ssh/config"
target = "~/.ssh/config"

Keyboard shortcuts