vfs.toml

Configure Yazi’s virtual filesystem services for remote file access

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

• Yazi Configuration
• Openers Configuration
• Theme Configuration