Skip to main content
SSHVFS mounts a directory of a remote server over SFTP: its folders and files appear as they are on the server. Set up the key and server as in SSH setup. It ships in @struktoai/mirage-node only; the browser package has no SSH client.

Install

ssh2 is a peer package that only this mount needs.

Configure

hostname connects to another address than host, and port to another port. Use MountMode.EXEC when python3 or js should run scripts from the mount.

Fields

string
required
DNS name or IP address of the remote.
string
Address to connect to instead of host.
number
default:"22"
SSH port.
string
Login user; unset uses the local user name.
string
secret
Password for password authentication; prefer identityFile.
string
Path to a private key; ~ is expanded. Unset tries the SSH agent and the default keys in ~/.ssh (id_ed25519, id_ecdsa, id_rsa, id_dsa).
string
secret
A private key’s own text, such as one a credential pointer reads from a secret store; offered after identityFile’s.
string
secret
Passphrase of an encrypted private key, from identityFile, privateKey or a default key.
string
default:"'/'"
Path on the remote that becomes the mount root.
number
default:"30"
Seconds to wait for the connection to be ready, authentication included.
string
Accepted but not applied: this backend does not verify host keys.
Fields marked secret are redacted in snapshots.

Authentication

The mount offers, in order, the key at identityFile, then the key text in privateKey, which a credential pointer can read from a secret store. Without either, it tries the SSH agent and the default keys in ~/.ssh. passphrase unlocks an encrypted key. password works too, but a key is preferred. The server needs SFTP turned on. Reads and writes go as far as the SSH account’s own file permissions allow.

Layout

The tree mirrors the server from root: /remote/logs/app.log is /srv/data/logs/app.log on the server.

Behavior

  • Host keys: not verified. knownHosts is accepted but not applied, so any host key is accepted.
  • Caching: listings are cached for 60 seconds by default. File bytes are served from cache without a check until the mount’s ttl:; an SSH mount does not accept read: fresh.
  • Running programs: this mount reads and writes files. To run programs on the server, use the SSH machine.

Integration

SSH answers these commands on the server, so fewer files are read. See Integration.
  • grep -r and rg: grep on the server finds which files hold the text, then only those are read, so nothing is missed. Every file is read when the server runs no commands (an SFTP-only account), its grep refuses an option (busybox), or it cannot read a file.
  • wc -l: wc -l on the server.
  • tail -f: tail -f on the server.
  • md5sum, sha256sum and the other hash commands: the matching sum tool on the server.
  • find: one find on the server.
  • du: one find on the server.
  • ls -R and tree: one find on the server.

VFS.md

The VFS.md an agent reads with SSH mounted at /<path>. <mode> is the mount’s mode: read, write or exec. The commands shown are those of a write mount.
Virtual FilesystemSupported Unix Commands for VFSUnix commands work on each path as on a local filesystem, as far as the path supports them:Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:Run man <cmd> or <cmd> --help for one command’s usage.