Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/sxyazi/yazi/llms.txt

Use this file to discover all available pages before exploring further.

The vfs.toml file configures virtual filesystem (VFS) services that enable Yazi to access remote files and special file systems.

​
File Location

  • Unix-like systems: ~/.config/yazi/vfs.toml
  • Windows: %AppData%\yazi\config\vfs.toml

​
What is VFS?

Yazi’s Virtual File System (VFS) allows you to:
  • Access remote files via HTTP/HTTPS
  • Browse cloud storage
  • Work with virtual/network file systems
  • Handle files that need special fetching logic

​
Configuration Structure

The VFS configuration consists of service definitions: 
[services]
service_name = { type = "Service", ... }

​
Default Configuration

The default vfs-default.toml is minimal: 
[services]
Currently, VFS services need to be explicitly configured as needed.

​
Service Types

VFS services can be configured for different protocols and use cases.

​
HTTP/HTTPS Service

Access files over HTTP/HTTPS: 
[services.http]
type = "Http"
base_url = "https://example.com/files/"
​
type
string
default:"Http"
Service type identifier
​
base_url
string
Base URL for HTTP requests
​
headers
table
Optional HTTP headers to include in requests
[services.http.headers]
Authorization = "Bearer token123"
User-Agent = "Yazi/1.0"

​
Custom Service

Define custom VFS services for specialized needs: 
[services.custom]
type = "Custom"
fetch_command = "my-fetch-script %s"
​
type
string
default:"Custom"
Service type identifier
​
fetch_command
string
Command to fetch files. Use %s as placeholder for the file URL.

​
Service Usage in File Opening

VFS services work with the opener and file opening rules. When a file with a VFS MIME type is opened, Yazi can use the configured service to fetch it.

​
VFS MIME Types

Yazi uses special MIME types for VFS files:
  • vfs/absent - File is not yet fetched
  • vfs/stale - Cached file is outdated
You can configure openers for these types in yazi.toml: 
# In yazi.toml
[opener]
download = [
  { run = "ya emit download --open %S", desc = "Download and open" },
  { run = "ya emit download %S", desc = "Download" },
]

[open]
rules = [
  # VFS files
  { mime = "vfs/{absent,stale}", use = "download" },
  # ... other rules
]

​
Complete Example

# HTTP service for remote files
[services.cdn]
type = "Http"
base_url = "https://cdn.example.com/"

[services.cdn.headers]
Authorization = "Bearer your-token-here"
User-Agent = "Yazi VFS Client"

# Another HTTP service with different base URL
[services.storage]
type = "Http"
base_url = "https://storage.example.com/files/"

​
Using VFS Services

​
Opening Remote Files

To open a remote file through VFS:
  1. Configure the VFS service in vfs.toml
  2. Configure opener rules for VFS MIME types in yazi.toml
  3. Navigate to a VFS URL in Yazi
  4. Open the file - Yazi will fetch it using the configured service

​
URL Format

VFS URLs typically follow this format: 
vfs://service_name/path/to/file
For example: 
vfs://cdn/images/photo.jpg
vfs://storage/documents/report.pdf

​
Advanced Configuration

​
Caching

Fetched VFS files are cached in Yazi’s cache directory. The cache location is configured in yazi.toml: 
# In yazi.toml
[preview]
cache_dir = ""  # Empty = use default cache directory

​
Authentication

For services requiring authentication, use headers: 
[services.private]
type = "Http"
base_url = "https://private.example.com/"

[services.private.headers]
Authorization = "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
X-API-Key = "your-api-key"
Be careful with storing credentials in configuration files. Consider using environment variables or secret management systems for sensitive data.

​
Timeout Configuration

Configure request timeouts for HTTP services: 
[services.slow]
type = "Http"
base_url = "https://slow-server.example.com/"
timeout = 60  # Timeout in seconds

​
Troubleshooting

​
Service Not Found

If you get “No such VFS service” error:
  1. Check that the service is defined in vfs.toml
  2. Verify the service name matches the VFS URL
  3. Ensure vfs.toml has no syntax errors

​
Fetch Failures

If files fail to fetch:
  1. Check network connectivity
  2. Verify the base URL is correct
  3. Check authentication headers if required
  4. Look at Yazi’s error messages for details

​
Cache Issues

If cached files are stale:
  1. Clear Yazi’s cache directory
  2. Restart Yazi to reload VFS configuration
  3. Check the file’s MIME type (should be vfs/stale for outdated cache)

​
Limitations

  • VFS is primarily designed for read-only access
  • Write operations to VFS files may not be supported
  • Performance depends on network speed and service latency
  • Some file operations may not work with VFS files

​
Use Cases

​
Remote File Browsing

Browse and preview remote files without downloading them all: 
[services.docs]
type = "Http"
base_url = "https://docs.example.com/api/files/"

​
Cloud Storage Integration

Integrate with cloud storage providers: 
[services.cloud]
type = "Http"
base_url = "https://api.cloud-provider.com/v1/files/"

[services.cloud.headers]
Authorization = "Bearer cloud-token"

​
CDN Content

Access content from CDNs: 
[services.cdn]
type = "Http"
base_url = "https://cdn.jsdelivr.net/"

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us