# alist-tvbox: an AList proxy server that builds TvBox subscriptions from your cloud drives > alist-tvbox sits between AList and TvBox, exposing a single subscription URL that merges cloud-drive accounts, Emby and Jellyfin servers, BiliBili and YouTube sources into one config. It is a Java server aimed at people who already run AList and want TvBox to see everything at once. **power721/alist-tvbox** — AList proxy server for TvBox, support playlist and search. - Repository: https://github.com/power721/alist-tvbox - Website: https://hub.docker.com/r/haroldli/xiaoya-tvbox - Stars: 3,134 · Forks: 589 - Language: Java - License: not declared - Published: 2026-09-24 · Updated: 2026-09-24 · Language: en - Canonical page: https://hysenlabs.com/projects/power721-alist-tvbox ## What alist-tvbox solves for TvBox users with several sources TvBox reads a JSON configuration that lists sites, parsers and search rules. If you keep your media on several cloud drives, plus an Emby server and maybe a Jellyfin instance, you end up maintaining several configs or hand-merging them. alist-tvbox is a proxy server that does the merging for you and serves the result at one URL, `http://ip:4567/sub/0`. The README describes it as an "AList proxy server for TvBox, support playlist and search". The audience is narrow and specific. You need an AList deployment, a TvBox client, and enough patience to edit JSON when the default aggregation is not what you want. The project also ships a web management UI, so the intended workflow is browser-based configuration rather than hand-written config files. Cloud drive coverage listed in the README includes Aliyun, Baidu, Quark, UC, 115, 123, Tianyi, 139, Thunder, PikPak and GuangYa, plus Emby, Jellyfin, Feiniu, BiliBili, YouTube and live-stream sources. That breadth is the point: one subscription URL, many backends. ## How the proxy builds a subscription from AList, plugins and sources The data flow is one-directional. alist-tvbox holds your source definitions and plugin metadata, generates a TvBox-compatible JSON, and serves it at the subscription path. TvBox fetches that JSON and renders the sites. Search and playlist handling happen on the server side, which is why the project calls itself a proxy rather than a config generator. Customisation happens through a backend JSON document. The README shows that `sites` entries can disable a built-in site by key, rename one, or add a new one, and that `blacklist.sites` and `blacklist.parses` remove entries by key, for example `csp_Bili` or `聚合`. Ordering is explicit: set an `order` field, lower values first, with built-in sources and plugins starting at 1000, subscription sources at 2000, and anything without an order defaulting to 9000. That numbering scheme is worth knowing before you start assigning values, because picking 1 for a site is legal but leaves no room above it. Python spider plugins take a different path. They are loaded through `csp_PyProxy` from a bundled `spring.jar`, and the original Python entry point and `ext` string are wrapped into the site definition. The README states that `loader`, `local_proxy_config` and the rest of the Python-side config are all encoded into `ext`, and that if `local_proxy_config` stays `{}`, local proxy acceleration is not enabled. That is the kind of detail that decides whether playback goes through your server or straight to the client. ## Installing alist-tvbox with Docker and pointing TvBox at it The README offers a build path and a run path. Building from source uses Maven: ```bash mvn clean package ``` After that, the README runs the jar directly with `java -jar target/alist-tvbox-1.0.jar`. There is also a shell installer, `sudo bash -c "$(curl -fsSL https://d.har01d.cn/update_xiaoya.sh)"`, which the README lists under Run. If you prefer not to run a remote script, the Docker route is more transparent. The simplest container starts the server on port 4567 with the default admin credentials from the README: ```bash docker run -d -p 4567:4567 --restart=always --name=alist-tvbox haroldli/alist-tvbox ``` A fuller example from the README maps an internal AList port, mounts a data volume and sets an environment variable: ```bash docker run -d -p 4567:4567 -p 5344:80 -e ALIST_PORT=5344 -v /opt/alist-tvbox:/data --restart=always --name=xiaoya-tvbox haroldli/xiaoya-tvbox:latest ``` Here `ALIST_PORT=5344` is passed into the container and `-p 5344:80` exposes the container's port 80 on host port 5344. The README gives the login as username `admin`, password `admin`; change that before exposing the server. Then point TvBox at `http://ip:4567/sub/0`, where `ip` is the host running the container. If TvBox loads an empty or partial list, the first thing to check is the backend JSON, not the client. ## Where alist-tvbox gets in the way: JSON editing, defaults and the licence gap The customisation model assumes you are comfortable with JSON and with key names that are not self-documenting. To disable a site you need its exact key, such as `csp_Bili`. To add a plugin you need a correctly base64-encoded `ext` string containing a `loader`, an `api` and a source. The README shows the shape of that string but not a generator, so in practice you build it by hand or copy an existing entry and edit it. A single malformed character in the base64 payload produces a plugin that silently fails to load. Ordering is another place where the defaults surprise people. A site with no `order` field lands at 9000, below subscription sources at 2000 and above nothing else. If you add a site and it appears at the bottom, that is why. The larger gap is licensing. The repository entry lists the licence as unknown, and the README does not state one. For a self-hosted tool that proxies cloud-drive accounts, that matters: you cannot reason about redistribution or commercial use from what is published. Treat it as something to resolve before you build it into anything shared. Finally, alist-tvbox is the wrong tool if you do not run AList. It is an AList proxy, so without an AList backend the aggregation has nothing to aggregate. If you only want one cloud drive visible in TvBox, a direct config is less moving parts than a server, a database volume and a plugin loader. ## alist-tvbox against a plain AList plus hand-written TvBox config The obvious alternative is running AList on its own and writing the TvBox JSON yourself. The difference is where the merging happens. With plain AList, each drive is an AList storage, and TvBox talks to AList through whatever site definitions you write. You control every field, and there is no intermediate server to keep updated. The cost is that every new drive, every Emby server and every Python plugin is manual work, and search across sources is whatever TvBox can do on its own. alist-tvbox moves that work server-side. You register sources once, and the generated subscription reflects them. The README also mentions offline download for 115, GuangYa and Thunder, and local proxy acceleration for plugins, which plain AList does not provide at this layer. The trade is a second service to run and a JSON dialect to learn, including the `order` scale and the `ext` encoding. If you change sources often, the proxy earns its place. If your setup is static, it mostly adds a container. The project also points to OpenList at `https://github.com/power721/PowerList`, listed in the README as a related project by the same author. That is worth reading if you want to understand the author's direction beyond alist-tvbox itself. ## Maintenance, upgrade cost and what the release cadence implies The last push was on 2026-09-21, and the most recent releases are 1.93.0 on 2026-09-21, 1.92.0 on 2026-09-20 and 1.91.0 on 2026-09-18. Three releases in four days suggests active work on this repository. It also means version churn: if you pin an image tag, expect to move it often, and if you track `latest`, expect the backend JSON schema to be the thing that breaks rather than the container. The upgrade cost is mostly in the configuration, not the binary. The README documents `sites`, `parses`, `blacklist`, `order`, and the plugin `ext` format. A release that changes how any of those are interpreted will require editing your backend JSON, and there is no migration tool mentioned. Keep a copy of your working config outside the container, and note that the fuller Docker example mounts `/opt/alist-tvbox` at `/data`, which is presumably where that state lives. On licensing, the repository lists the licence as unknown. That is not legal advice, but it is a practical signal: without a stated licence you have no explicit grant to redistribute, and the README does not clarify. If the project is going into a shared or commercial environment, that question comes before the deployment. ## Conclusion alist-tvbox is for people who already run AList and want TvBox to read one aggregated subscription instead of juggling several configs, and who are comfortable with Docker and JSON editing. If you do not run AList, or you only need one cloud drive in TvBox, the extra proxy layer adds work without adding much. Before adopting it, check the licence situation, since the repository does not state a licence; verify which AList version your image expects; and confirm whether local proxy acceleration is actually enabled in your plugin ext, because the README says an empty local_proxy_config leaves it off. ## FAQ ### What port does alist-tvbox use, and what is the subscription URL? The README runs the container with `-p 4567:4567`, so the server listens on port 4567, and the TvBox config URL is `http://ip:4567/sub/0`. The fuller Docker example also maps port 5344 on the host to port 80 in the container and sets `ALIST_PORT=5344`. ### What are the default alist-tvbox login credentials? The README lists username `admin` and password `admin`. Change them before exposing the server beyond your own network. ### How do I install alist-tvbox? The README gives three routes: build with `mvn clean package` and run the jar, use the shell installer at `https://d.har01d.cn/update_xiaoya.sh`, or run the Docker image `haroldli/alist-tvbox` with port 4567 published. The Docker route is the one the README documents in most detail. ### How do I disable a built-in site in alist-tvbox? Add its key to `blacklist.sites` in the backend JSON, for example `csp_Bili`, and add parser names to `blacklist.parses`. The README shows both keys in the same customisation example. ### Why is my alist-tvbox Python plugin not using local proxy acceleration? The README states that `loader`, `local_proxy_config` and the rest of the Python-side config are encoded into the plugin's `ext` string, and that if `local_proxy_config` remains `{}` then local proxy acceleration is not enabled. ## Sources - [Issues](https://github.com/power721/alist-tvbox/issues) - [power721/alist-tvbox on GitHub](https://github.com/power721/alist-tvbox) - [Project website](https://hub.docker.com/r/haroldli/xiaoya-tvbox) - [README](https://github.com/power721/alist-tvbox/blob/master/README.md) - [Releases](https://github.com/power721/alist-tvbox/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/power721-alist-tvbox