Common configuration

This page covers the shared mounting workflow. See the storage overview for backend-specific settings and authorization.

Add a storage adapter

Sign in to Foxel with permission to create adapters and open Storage Adapters.
Select Create Adapter, enter a name, and choose a type.
Choose a unique mount path such as /nas or /cloud/onedrive. Leave Sub Path empty initially.
Fill the settings from the corresponding guide, enable the adapter, and save.
Open the mount in the file manager and verify listing and downloading. If write access is needed, use a temporary small file to check upload, rename, and deletion.

Saving creates a configuration record; it does not verify every remote credential, directory permission, or operation.

Shared fields

These fields belong to the adapter record and sit outside the config object in individual guides.

Field	UI label	Description
`name`	Name	A recognizable label, such as “Home NAS”.
`type`	Type	Adapter identifier, such as `smb`, `pan115`, or `openlist`.
`path`	Mount Path	Unique location in the Foxel file manager; `/` means the root.
`sub_path`	Sub Path	Further directory selection below the backend root; support and resolution depend on the adapter.
`enabled`	Enabled	Enabled by default; disabled records are not loaded as active adapters.
`config`	Type-specific settings	Backend path, address, credentials, and tokens, depending on the type.

Mount path, backend root, and sub path

For example, expose movies/2026 inside the NAS share media as /cinema in Foxel:

json

{
  "name": "NAS Movies",
  "type": "smb",
  "path": "/cinema",
  "sub_path": "2026",
  "enabled": true,
  "config": {
    "server": "nas.example.com",
    "share": "media",
    "root": "/movies",
    "username": "foxel",
    "password": "YOUR_PASSWORD"
  }
}

path: /cinema is the Foxel display path; it does not create a NAS directory.
config.root: /movies selects the backend directory inside the share.
sub_path: 2026 selects a directory beneath that root.

Mount paths gain a leading / and lose a trailing /; duplicates are rejected. Prefer relative sub paths such as photos/2026, avoiding absolute paths and ... Leave the field blank first, verify the backend root, and then narrow the scope.

Root formats differ: Google Drive uses a folder ID; 115, 123Pan, and 189 Cloud use root_id; Quark and UC use root_fid; Cloudreve uses a cloudreve:// URI; S3 uses an object prefix. Quark currently ignores sub_path, while Telegram has no directory hierarchy. Follow the individual guide.

Credentials and values

The password field type means a password input and also covers Cookies, sessions, and tokens. Paste the full value unchanged.
“No” in the Required column applies to an individual field. Some drivers still require an authentication group, such as a token or a complete username/password pair for Seafile.
Example credentials are placeholders. JSON booleans use true / false, without quotes.
Saving keeps fields declared for the selected adapter type. OpenList, AList, and other drivers’ custom options do not carry over.
OAuth refresh tokens must match the issuing application credentials. Cookies and session strings identify a logged-in account. Protect them when backing up configuration.

Downloads, previews, and redirects

Some adapters expose enable_direct_download_307, disabled by default. When enabled, supported download requests may redirect to an upstream address. Clients must reach that address, and temporary links, browser sessions, headers, or IP restrictions may affect access.

Disable this option first when listings work but downloads or previews fail. Foxel still needs server-side access to the remote storage address.

Capacity display

Some adapters do not implement quota reporting. A - does not necessarily indicate a connection failure. Supported drivers may report the quota for an entire account or filesystem instead of a directory size. Capacity results are currently cached for about one hour, so changes after uploads may not appear immediately.

Troubleshooting order

Empty listing or missing mount: check enabled status, duplicate paths, backend root, and directory permissions.
401 or login error: check matching credentials, session validity, and remote verification requirements.
403 or write failure: check write permissions, quota, and driver limitations.
Timeout: check DNS, ports, proxies, and routing from the Foxel server or container. Container localhost refers to that container.
Large transfer failure: verify a small file first, then check proxy body limits, timeouts, temporary disk space, and adapter file-size limits.

Backend behavior and fields follow the Foxel implementation. Each guide includes references for service and authorization background.