Deploying a Virtual File System

The idea behind VFS

The Virtual Filesystem (VFS) connector lets you compose storages together to form a single unified filesystem regardless of what those storages are and where they are located. It’s arguably the most powerful building block in Filestash, allowing you to federate data from many systems and make them behave like one cohesive storage your users can access.

The real power come when you combine it with the existing authentication and authorisation mechanism and any other plugins like the sftp gateway which expose that same data over SFTP or MCP for agents to consume while staying in control of everything.

Scaffold for VFS

A typical VFS configuration is a list of mount points mapped to storage specifications. It takes the following form:

/folderA/ {"type": "local", ... }
/folderA/childOfA/ {"type":"azure", ...}

/folderB/ {"type": "local", "path": "/mnt/" ... }

Each mount point associates the path it will be available from alongside the configuration of the storage in a JSON format. The storage provider is identified through its type key, along with provider specific configuration fields.

The type key can reference any storage plugin installed in your Filestash instance. Common examples include: s3, sftp, ftp, nfs, smb, local, sharepoint, and many more. The complete list can be found in the storage plugin reference.

Storage Specs

Each storage type has its own specification. For example, S3 requires at minimum an access_key_id and a secret_access_key; an SFTP server typically needs a hostname, username, and password; Azure Blob requires an account_name and an account_key, etc.

To know which configuration fields are required for a storage provider, you have two approaches:

Option A: Infer it from the provider’s specification

When Filestash asks you to fill in connection details either through the admin console or when the authentication middleware is disabled, the form shown is generated directly from the storage specification.

These specifications are also visible from your instance: requesting /api/backend returns the complete list. Taking SFTP as an example, you will find something like:

{
  "status": "ok",
  "result": {
    ...
    "sftp": {
      "type": { ... }
      "hostname": { ... },
      "username": { ... },
      "password": { ... },
      ...
      "port": { ... },
      "passphrase": { ... },
      "hostkey": { ... },
    },
    ...
  }
}

From those specs, you know which fields exist and can craft a VFS entry accordingly:

/directoryA/ {"type":"sftp","hostname":"test.rebex.net","username":"demo","password":"password"}

Option B: using your browser developer console

When the authentication middleware is disabled for a storage provider, Filestash prompts the user directly for connection details. If you open your browser’s Developer Console and inspect the Network tab, you will see a request sent to /api/session when submitting the form. Clicking on the request payload will show something like:

{"type":"sftp","hostname":"test.rebex.net","username":"demo","password":"password","path":null,"port":null,"passphrase":null,"hostkey":null}

This payload represents the exact spec you can inject into the VFS configuration.

Mix it with variables

Once you have a working storage definition in place, you may want to parameterize it. Parameters can come from two places:

1. Attributes returned by the identity provider (exposed in the template context)
2. Environment variables, which are available through the .ENV_ prefix

With these, you can build dynamic and user-specific configurations. For example:

/projects/ {"type": "local", "password": "test", "path": "/home//Documents/"}
/projects/azure/ { "type":"azure", "account_name":"","account_key":""}

Under the hood, we use the Go template language to process variables and expressions, which gives you a lot of flexibility when building dynamic configurations. You can find the full template syntax documentation here.