AList User Guide

AList is a self-hosted file list program that puts dozens of cloud drives, object stores, and network protocols behind a single web interface. Point it at your Aliyundrive, OneDrive, Google Drive, S3 bucket, local disk, SMB share — over 90 storage backends in all — and AList presents them as one browsable, searchable file tree that you can preview, download, upload to, and even re-share over WebDAV, FTP, SFTP, or an S3-compatible endpoint.

It is a single Go binary (powered by the Gin web framework and a Solid.js front end). There is no database server to install, no runtime to provision: download one executable (or pull one Docker image), run it, and open your browser.

Note

This guide covers using and operating AList day to day: installing it, mounting storages, browsing and sharing files, and the access protocols. For architecture, the full configuration reference, deployment hardening, the driver-development model, and internals, see the AList Admin Guide.

1. Quick Start

The fastest path from zero to a working file list is three commands. Pick the binary or the Docker route.

Binary (Linux/macOS)

# 1. Download and extract the release for your platform, then run:
./alist server

INFO[0000] reading config file: data/config.json
INFO[0000] config file not exists, creating default config file
INFO[0000] Successfully created the admin user and the initial password is: a1b2c3d4
INFO[0000] start HTTP server @ 0.0.0.0:5244

Docker

docker run -d \
  --name alist \
  -p 5244:5244 \
  -v ./alist-data:/opt/alist/data \
  --restart unless-stopped \
  xhofe/alist:latest

# Read the auto-generated admin password from the container logs:
docker logs alist 2>&1 | grep password

Then:

1. Open http://<your-server-ip>:5244 in a browser.
2. Click Login (top-right) and sign in as admin with the password printed in the startup log.
3. Go to the management panel at http://<your-server-ip>:5244/@manage.
4. Open Storages → Add, choose a driver (e.g. Local, Onedrive, S3), fill in its fields, and save.
5. Return to the home page — your storage now appears as a folder under its mount path.

Important

The initial admin password is shown only once, in the first-run log. AList stores it as a hash and cannot print it again. If you miss it, reset it with ./alist admin set <new-password> (binary) or docker exec -it alist ./alist admin set <new-password> (Docker). See Managing the admin account.

Tip

AList listens on 0.0.0.0:5244 by default — reachable from any machine on your network. Before exposing it to the internet, read Securing your instance.

2. What AList Does

AList sits between you and your storage providers. You mount each provider once (with its credentials), and AList gives every mounted backend a uniform interface:

        Browser / WebDAV client / FTP client / S3 SDK / AI assistant (MCP)
                                  │
                                  ▼
                          ┌───────────────┐
                          │     AList      │   one mount tree: /onedrive, /s3, /local …
                          └───────────────┘
              ┌──────────────┬──────┴───────┬──────────────┐
              ▼              ▼              ▼              ▼
         OneDrive      Aliyundrive       S3 bucket     Local disk   … 90+ backends

What you can do with a mounted tree:

• Browse and preview — folders, images (gallery mode), video and audio (with subtitles and lyrics), PDFs, Office documents, Markdown, code, and plain text, all in the browser.
• Download — single files, or whole folders as an archive; copy permanent direct links.
• Upload, create, rename, move, copy, delete — including moving or copying files between two different storages (e.g. OneDrive → S3).
• Offline download — hand a magnet link or URL to aria2, qBittorrent, Transmission, or a built-in HTTP downloader and have the result land directly in a cloud storage.
• Search — across your mounted tree, optionally backed by a full-text index.
• Share and re-serve — expose the tree (or a sub-path) over WebDAV, FTP/SFTP, or an S3-compatible endpoint, or create password-protected public share links.
• Protect — per-path passwords, hidden files, signed links, and role-based permissions for multiple users.
• Connect AI assistants — an optional MCP server lets tools like Claude Desktop list, read, and manage files.

Note

AList is a front end to storage you already own. It does not store your files itself — it proxies or redirects to the underlying provider. The only local state AList keeps is its configuration, the storage list, users, and (optionally) a search index. See the Admin Guide for the data model.

3. Installation

3.1 Requirements

AList ships as a statically-linked binary, so requirements are minimal.

Tip

By default AList uses an embedded SQLite database stored inside data/. You do not need to install or run a database server. MySQL and PostgreSQL are optional alternatives covered in the Admin Guide.

3.2 Install methods

Pre-built binary

1. Download the archive for your OS/arch from the project's releases.

2. Extract it to a directory you control:

   mkdir -p /opt/alist && cd /opt/alist
   tar -zxvf alist-linux-amd64.tar.gz
   

3. Make it executable and run:

   chmod +x alist
   ./alist server
   

Docker

docker run -d \
  --name alist \
  -p 5244:5244 \
  -v ./alist-data:/opt/alist/data \
  --restart unless-stopped \
  xhofe/alist:latest

The image exposes ports 5244 and 5245 and stores all state in the volume /opt/alist/data.

Docker Compose

services:
  alist:
    image: xhofe/alist:latest
    container_name: alist
    ports:
      - "5244:5244"
    volumes:
      - "./alist-data:/opt/alist/data"
    restart: unless-stopped

docker compose up -d

Caution

Always bind-mount /opt/alist/data (Docker) or preserve the data/ directory (binary). It holds your configuration, your storage list, your users, and the JWT secret. Losing it means re-configuring every storage from scratch.

3.3 First run

On the very first alist server, AList:

1. Creates data/config.json with sensible defaults.

2. Creates the admin user with a random initial password and prints it to the log:

   Successfully created the admin user and the initial password is: <random>
   

3. Starts the HTTP server on 0.0.0.0:5244.

Capture that password immediately, or reset it (next section).

4. Running AList

AList is a single command with sub-commands. The main one is server.

4.1 Starting and stopping

# Typical foreground run with a custom data directory:
./alist server --data /var/lib/alist

INFO[0000] reading config file: /var/lib/alist/config.json
INFO[0000] start HTTP server @ 0.0.0.0:5244

Note

On Windows, ./alist stop behaves the same as kill (there is no Unix-signal daemon). Use a service manager (NSSM, Task Scheduler) for unattended Windows operation.

Tip

For real production use, run AList under a process supervisor — systemd, Docker's --restart, or similar — rather than the built-in start/stop daemon. The Admin Guide has a ready-to-use systemd unit.

4.2 Global flags

These flags work on server and most sub-commands:

./alist server --data ./data --debug --log-std

4.3 The version command

./alist version

Built At: ...
Go Version: go1.25.0 linux/amd64
Author: Xhofe <[email removed]>
Commit ID: d0cec67
Version: v3.x.x
WebVersion: ...

5. Mounting Storages

A storage is one mounted backend: a driver plus the credentials and options it needs, attached at a mount path like /onedrive or /photos/family.

5.1 Adding a storage

1. Log in as admin and open the management panel (/@manage).
2. Go to Storages → Add.
3. Choose a Driver from the dropdown (see the catalog).
4. Set the Mount path — where this storage appears in your tree (e.g. /cloud/onedrive).
5. Fill in the driver-specific fields (tokens, keys, root folder, region, …). Each field has inline help.
6. Set any common options (cache, sort order, proxy mode — see common settings).
7. Save. AList initializes the driver and, if successful, the mount appears on the home page.

Tip

Many cloud drivers (Aliyundrive, OneDrive, Google Drive, 115, …) authenticate with OAuth tokens or cookies rather than a username/password. The field help text and the official documentation at alistgo.com walk through obtaining each one. AList only stores what you paste in.

Important

A storage's mount path must be unique. Mounting two storages at the same path is not allowed. Use nested paths (/a, /a/b) freely — AList resolves the most specific match.

5.2 Common storage settings

Every storage, regardless of driver, exposes this shared set of options:

Note

Proxy vs. redirect. For many cloud drives AList can hand the browser a temporary direct link from the provider (fast, no AList bandwidth). Some drivers must proxy (their links are IP- or header-locked); those are marked internally as proxy-only. Enable Web proxy when you want every download to flow through AList — e.g. to apply a single public URL, add speed limits, or hide the backend.

5.3 Storage driver catalog

AList ships 90+ storage drivers. You only configure the ones you use. They fall into these families:

Mainstream cloud drives

Chinese cloud drives

Object storage & network protocols

Other AList servers & developer integrations

Virtual / meta drivers — these wrap other mounted storages rather than talking to an external provider:

Tip

The exact field list for each driver is shown in the Add-Storage form and documented at alistgo.com. The catalog above tells you which driver to pick; the form tells you what to fill in.

5.4 Editing, disabling, and removing storages

• Edit — change credentials or options at any time; AList re-initializes the driver on save.
• Disable — toggle a storage off (it disappears from the tree but keeps its config). From the CLI: ./alist storage disable <mount-path>.
• Delete — remove the storage and its configuration permanently.
• List from the CLI — ./alist storage list opens an interactive table of every storage (ID, driver, mount path, enabled).

# Inspect storages without opening the web UI:
./alist storage list

# Disable a misbehaving mount quickly:
./alist storage disable /onedrive

6. Everyday Usage

6.1 Browsing, previewing, and downloading

From the home page you navigate the merged tree like any file browser:

• Click a folder to open it; click a file to preview it.
• Images open in a gallery with next/previous navigation.
• Video and audio stream in-browser, with subtitle and lyric support.
• Documents (PDF, Office, Markdown, code, text) render inline.
• Download a file with the download button, or select a folder and download it as a package.
• Copy direct link / permalink to share a stable URL to a single file.

Direct download URLs follow simple patterns you can use in scripts:

Tip

Append a download to any path to fetch it with curl/wget. If the storage has Enable sign on, the link includes a ?sign= token — copy the full signed URL from the UI.

6.2 Managing the admin account

The admin account is special — it always exists and always has full permissions. Manage it from the CLI:

# Forgot the admin password? Set a known one:
./alist admin set 'My$tr0ngPass'

INFO admin user has been updated:
INFO username: admin
INFO password: My$tr0ngPass

Warning

Anyone with shell access to the AList host can reset the admin password with alist admin set. Treat host access as equivalent to full AList admin access, and protect the data/ directory accordingly.

6.3 Users, roles, and per-path permissions

Beyond admin, you can create additional users (management panel → Users) and assign them roles. Each role grants a set of fine-grained permissions, optionally scoped to specific paths.

The permission set AList enforces:

A built-in guest user controls what anonymous (not-logged-in) visitors can do. Disable it to require login for everything.

Note

Permissions are evaluated per path. A role can grant read everywhere but write only under /uploads, for example. The Admin Guide covers role configuration and the permission model in depth.

6.4 Hiding and password-protecting paths (Meta)

Meta rules attach behavior to a path and its children, configured under management → Metas:

• Password — require a password to enter a folder.
• Hide — hide files matching a regex from listings.
• Readme — show a README on a folder page.
• Write — allow guest uploads into a specific folder.

Tip

Meta rules cascade. Set a password on /private and every subfolder inherits it unless you add a more specific rule. Combine Hide with the See hidden files permission to keep files out of the public listing but visible to trusted users.

7. Sharing Files

7.1 Public share links

Create a share (management → Shares, or the share action on a file/folder) to hand out a link that does not require an AList account:

• Optional password protection.
• Optional expiry.
• Scoped to a single file or a whole sub-tree.

Share URLs use the /s/<share_id> (browse), /sd/<share_id> (download), and /sp/<share_id> (proxy) patterns.

7.2 WebDAV access

AList re-serves your whole tree over WebDAV at the /dav path — mount it in Windows Explorer, macOS Finder, or apps like RaiDrive, Kodi, or Infuse.

URL:      http://<host>:5244/dav
Username: <your AList username>
Password: <your AList password>

Note

WebDAV honors the same permissions as the web UI (via the WebDAV read / WebDAV manage permissions). The admin account can also authenticate over WebDAV using its API token as a Bearer credential.

7.3 FTP, SFTP, and S3 endpoints

AList can additionally expose your tree as:

• An FTP / FTPS server (default :5221) — for legacy clients and appliances.
• An SFTP server (default :5222) — password or SSH-public-key auth.
• An S3-compatible endpoint (default :5246) — point any S3 SDK or tool at it.

These are off by default and are enabled in config.json (see the Admin Guide). FTP/SFTP access requires the FTP access permission on the user.

# Once SFTP is enabled, connect with any SSH client:
sftp -P 5222 admin@<host>

7.4 Connecting an AI assistant (MCP)

AList includes a Model Context Protocol (MCP) server so AI assistants (Claude Desktop, and other MCP clients) can list, read, and manage your files as tools.

• HTTP mode — enable the MCP server in config.json (default port 5248); clients connect over Streamable HTTP.
• STDIO mode — run ./alist mcp --user admin to serve a single session over standard input/output, ideal for desktop assistant integrations.

# Launch an MCP STDIO session acting as the admin user:
./alist mcp --user admin

Important

MCP access is gated by the MCP access / MCP manage permissions and requires authentication. Only give MCP-manage to assistants you trust to modify files.

8. Power Features

8.1 Copying files between storages

Select a file or folder in one storage and copy or move it into another — AList streams the data between backends for you (e.g. pull a file from a friend's shared Aliyundrive into your own S3 bucket). Large transfers run as background tasks you can monitor, retry, or cancel under management → Tasks.

8.2 Offline download

Hand AList a URL or magnet link and let a download engine fetch it directly into a cloud storage, without routing the bytes through your own machine. Supported engines:

Configure the engine's connection details under management → Settings, then use the offline download action on a destination folder.

Tip

Native cloud offline-download (115, PikPak, Thunder) is usually fastest — the provider fetches the torrent on its own servers and the result appears in your drive with no transfer to AList at all.

8.3 Search

Use the search box to find files across your mounted tree. AList offers three search backends (set in the Admin settings):

• Database (default) — indexes file metadata in AList's own database; lightweight.
• Bleve — an embedded full-text index, no external service.
• Meilisearch — an external Meilisearch instance for large libraries and fast full-text search.

For indexed search, build the index once from management → Settings → Index, then keep it current (manually or via auto-update). You can exclude individual storages from indexing with Disable index.

8.4 Archive preview and extraction

AList can look inside archives (.zip, .7z, .rar, .iso, and more) without extracting them — browse the contents, preview a file, or extract to a destination — subject to the Read archives and Decompress permissions. Archive direct-access URLs use the /ad/, /ap/, and /ae/ patterns.

8.5 Encryption, chunking, and media (.strm)

These virtual drivers transform another storage:

• Crypt — wrap any backend so files are encrypted at rest and decrypted on the fly (compatible with rclone's crypt). Mount the encrypted backend, then mount Crypt on top of it.
• Chunker — split oversized files into pieces so they fit a backend's per-file size limit, transparently reassembled on download.
• Strm — generate .strm pointer files for a media library so Emby/Jellyfin/Plex can stream from your cloud storage.

9. Securing Your Instance

AList defaults are convenient, not locked-down. Before exposing it publicly, do at least the following:

• [ ] Reset the admin password to a strong value: ./alist admin set <strong-password>.
• [ ] Enable 2FA on the admin account (management → Profile).
• [ ] Put AList behind HTTPS — a reverse proxy (Caddy, Nginx, Traefik) is the easiest path; AList can also terminate TLS itself (see Admin Guide).
• [ ] Restrict the guest user or disable anonymous access entirely.
• [ ] Tighten CORS — the default allows all origins (*); narrow it in config.json for a public deployment.
• [ ] Lock down the data/ directory — it contains the JWT secret and all credentials.
• [ ] Leave TLS verification ON — do not set tls_insecure_skip_verify; AList warns loudly that doing so exposes all storage traffic to interception.

Caution

Disabling TLS certificate verification (tls_insecure_skip_verify) makes every connection AList opens to your storage providers vulnerable to man-in-the-middle attacks, which can leak credentials or tamper with your data. AList prints an explicit security warning when it is on. Only use it if you fully understand the risk.

Note

The full hardening checklist, TLS setup, reverse-proxy examples, sign/secret rotation, and the complete config reference are in the AList Admin Guide → Security.

10. Troubleshooting

Error: config file not exists, creating default config file

Cause: First run, or the data/ directory was moved/deleted. Solution: This is informational on first start. If it appears unexpectedly, you launched AList with the wrong --data path — point it back at your real data directory. Prevention: Always pass the same --data (or keep the working directory consistent); bind-mount /opt/alist/data in Docker.

I missed the initial admin password

Cause: The random password is logged only once, at first start. Solution: Set a new one: ./alist admin set <password> (or ./alist admin random to generate one). Prevention: Capture the first-run log, or reset to a known value immediately after install.

Error: start HTTP server never appears / port already in use

Cause: Another process is bound to 5244, or the HTTP port is disabled in config. Solution: Free the port, or change scheme.http_port in config.json. Confirm http_port is not set to -1 (which disables HTTP). Prevention: Decide your port up front and reverse-proxy onto it.

A storage shows an error / red status after saving

Cause: Bad credentials, an expired token, or the backend is unreachable. Solution: Edit the storage and re-enter the token/cookie; check the Status message on the storage row for the driver's specific error. For OAuth drivers, re-run the token-acquisition flow. Prevention: Refresh tokens before they expire; some drivers refresh automatically once initialized.

Mounting Tencent Weiyun causes a crash / nil pointer

Cause: A known issue with the Weiyun driver under certain accounts (community issue #9551). Solution: Disable the Weiyun storage (./alist storage disable <path>) to restore service, and track the upstream issue for a fix. Prevention: Test new cloud drivers on a non-critical instance before relying on them.

failed to list objs: PROPFIND /: 400 on a WebDAV-backed storage

Cause: The upstream WebDAV server rejected the listing request (community issue #7771) — often a wrong root path or an incompatible server. Solution: Verify the WebDAV URL and root folder; some servers need the path with or without a trailing slash. Try toggling proxy mode. Prevention: Confirm the WebDAV endpoint works in a standalone client first.

Copying a large file between two cloud drives runs out of memory

Cause: Some cross-drive copies buffer aggressively (community issue #9374). Solution: Enable Web proxy with range support on the source storage, lower the relevant task concurrency in Settings, or use native offline-download where available. Prevention: Prefer same-provider operations or native cloud transfers for very large files.

WebDAV / FTP login is refused

Cause: The user lacks the WebDAV read (or FTP access) permission, or the protocol is disabled in config. Solution: Grant the relevant permission to the user's role; confirm FTP/SFTP is enabled in config.json. For admin-over-WebDAV, use the API token as a Bearer credential. Prevention: Map out which users need which protocols when you create roles.

Files appear twice when using Alias + indexed search

Cause: An Alias storage and its underlying storages are both indexed (community issue #9489). Solution: Set Disable index on either the alias or the underlying mounts so each file is indexed once. Prevention: Decide a single canonical mount for indexing when you use Alias.

11. FAQ

Q: Does AList store my files? No. AList is a front end to storage you already own. It proxies or redirects to the underlying provider; the only local state is configuration, the storage/user list, and an optional search index.

Q: Do I need a database server? No. AList uses an embedded SQLite database inside data/ by default. MySQL/PostgreSQL are optional (Admin Guide).

Q: How many storages can I mount? There is no fixed limit — mount as many as you need, including multiple accounts of the same provider at different paths.

Q: Can two storages share a mount path? No — mount paths are unique. Use nested paths, or an Alias driver to merge several into one virtual folder.

Q: How do I reset the admin password? ./alist admin set <password>, or ./alist admin random for a generated one. Requires shell access to the host.

Q: What's the default port? HTTP on 5244. HTTPS, FTP (:5221), SFTP (:5222), S3 (:5246), and MCP (:5248) are off by default and enabled in config.

Q: Can I run AList behind a reverse proxy with a sub-path? Yes. Set site_url to the public base URL (including any sub-path); AList adjusts its routes and links accordingly. See the Admin Guide.

Q: How do I let visitors upload without an account? Add a Meta rule with write enabled on a specific folder, and grant the guest user the Write permission there. Scope it tightly.

Q: Can AI assistants use AList? Yes — enable the MCP server (HTTP mode) or run ./alist mcp (STDIO mode) and connect an MCP client like Claude Desktop. Access is permission-gated.

Q: Does AList support encrypted storage? Yes — the Crypt driver encrypts/decrypts another backend transparently and is compatible with rclone's crypt format.

Q: How do I download a whole folder? Select the folder and use package download, or use the /d/<path> URL pattern per file in a script.

Q: Where does the search index live? Database search uses AList's own DB. Bleve stores an index under data/. Meilisearch runs as a separate external service you point AList at.

Q: Is there an API? Yes — AList exposes a full REST API (the web UI is built on it). Endpoints, auth, and the admin API are documented in the Admin Guide; public API reference is also published by the project.

Q: How do I update AList? Replace the binary (or pull a new Docker image) and restart. Your data/ directory carries forward; AList migrates its config and database on startup.

12. Command Reference

Default ports

Direct-link URL patterns