> ## 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.

# 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:

```toml theme={null}
[services]
service_name = { type = "Service", ... }
```

## Default Configuration

The default `vfs-default.toml` is minimal:

```toml theme={null}
[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:

```toml theme={null}
[services.http]
type = "Http"
base_url = "https://example.com/files/"
```

<ParamField path="type" type="string" default="Http">
  Service type identifier
</ParamField>

<ParamField path="base_url" type="string">
  Base URL for HTTP requests
</ParamField>

<ParamField path="headers" type="table">
  Optional HTTP headers to include in requests

  ```toml theme={null}
  [services.http.headers]
  Authorization = "Bearer token123"
  User-Agent = "Yazi/1.0"
  ```
</ParamField>

### Custom Service

Define custom VFS services for specialized needs:

```toml theme={null}
[services.custom]
type = "Custom"
fetch_command = "my-fetch-script %s"
```

<ParamField path="type" type="string" default="Custom">
  Service type identifier
</ParamField>

<ParamField path="fetch_command" type="string">
  Command to fetch files. Use `%s` as placeholder for the file URL.
</ParamField>

## 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`:

```toml theme={null}
# 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

```toml theme={null}
# 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`:

```toml theme={null}
# In yazi.toml
[preview]
cache_dir = ""  # Empty = use default cache directory
```

### Authentication

For services requiring authentication, use headers:

```toml theme={null}
[services.private]
type = "Http"
base_url = "https://private.example.com/"

[services.private.headers]
Authorization = "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
X-API-Key = "your-api-key"
```

<Warning>
  Be careful with storing credentials in configuration files. Consider using environment variables or secret management systems for sensitive data.
</Warning>

### Timeout Configuration

Configure request timeouts for HTTP services:

```toml theme={null}
[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:

```toml theme={null}
[services.docs]
type = "Http"
base_url = "https://docs.example.com/api/files/"
```

### Cloud Storage Integration

Integrate with cloud storage providers:

```toml theme={null}
[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:

```toml theme={null}
[services.cdn]
type = "Http"
base_url = "https://cdn.jsdelivr.net/"
```

## See Also

* [Yazi Configuration](configuration/yazi)
* [Openers Configuration](configuration/openers)
* [Theme Configuration](configuration/theme)