free-one-api's answer to unstable reverse-engineered adapters is a heartbeat check and an auto-disable

The README hands paid traffic to a different repository

The one direction this project is explicit about is which traffic does not belong here. The opening note says that if you want the official, paid LLM interfaces behind a standard OpenAI API, you should use songquanpeng/one-api, and that free-one-api can also be paired with one-api. That is the author's own boundary drawn in advance: this repository is the reverse-engineered tier, and one-api is the tier that talks to paid providers.

The project blurb makes the same point in blunter terms, listing ChatGPT, gpt4free, Bard, Claude, HuggingChat and Tongyi Qianwen as AI 的破解版, that is, cracked versions. Read together, the two statements set the scope honestly. Nothing here is an API vendor with its own quota and billing. It is a translation layer over front ends that were never meant to be called this way, and the maintainer knows it.

Heartbeat checks and auto-disable assume the adapters will break

The feature list is six bullets: automatic load balancing, a Web UI, streaming mode, support for several LLM reverse libraries, a heartbeat detection mechanism that automatically disables unusable channels, and run logging.

Three of those six exist to absorb the same failure. Alongside them the author asks for contributors and writes that there are too many adapters, that they are very unstable, that one person cannot keep up, and that help is wanted to test each adapter and find new reverse-engineered libraries. Probing a channel, taking it out of rotation when it stops answering, and spreading load over what is left is a direct answer to endpoints that fail without warning.

Note what is not there. No probe interval, no failure threshold, no rule for putting a channel back, no per-adapter setting. The README is one page of Chinese and names none of them, so the behaviour you actually get is whatever the code in free_one_api/ does, not what the page promises.

Seven reverse-engineering libraries in requirements.txt, two of them pinned

The dependency list is the shortest honest summary of what this gateway is:

quart
aiosqlite
PyYaml
revChatGPT
tiktoken
setuptools<81
claude-api
bardapi
hugchat
g4f==8.1.6
revTongYi
colorlog
re_gpt==4.0.0

Seven of the thirteen entries are reverse-engineering libraries, and five of those seven carry no version constraint at all: revChatGPT, claude-api, bardapi, hugchat and revTongYi resolve to whatever their authors last published when the image is built. The only pins are g4f==8.1.6 and re_gpt==4.0.0, plus an upper bound of setuptools<81 on a packaging tool rather than on any chat backend.

The floating entries are the fragile ones. A library whose job is to imitate a web front end breaks when that front end changes, and unpinned means the breakage arrives on your build machine rather than on a schedule you chose. Note too that re_gpt appears in the dependency list without a matching product name in the blurb, which names six services.

The image installs a GPU runtime and then deletes it by absolute path

The Dockerfile pins its base to an exact patch level and then cleans up after its own dependency install:

RUN pip install --no-cache -r requirements.txt \
    && pip uninstall torch tensorflow transformers triton -y \
    && rm -rf /usr/local/lib/python3.10/site-packages/nvidia*

The FROM line is python:3.10.13-slim-bullseye, so the site-packages path in that rm is hardcoded to a Python 3.10 layout that the base tag already fixes. The two facts have to move together or the cleanup misses. Between them, the install step pulls whatever the reverse-engineering libraries declare, and the next step removes torch, tensorflow, transformers and triton along with the nvidia wheels, which tells you those libraries arrive with a machine-learning runtime attached and the image is built specifically to shed it.

The same file also runs apt-get install -y git, yet no entry in requirements.txt is a VCS URL and nothing in the Dockerfile clones anything. The git client is there for something the file does not show.

The container ships the compiled web bundle and drops the tests

Three COPY lines decide what is inside the image:

# copy dist of web
COPY ./web/dist /app/web/dist
COPY ./free_one_api /app/free_one_api
COPY ./requirements.txt ./main.py /app/

The first of them copies web/dist, the compiled output of the Web UI, rather than the web sources it was built from. That is normal for a single-stage image and worth knowing before you expect to inspect the frontend in a running container.

More interesting is what never makes the trip. The repository root holds docs/, design/, assets/, test/, .github/, README.md and README_en.md, and none of them is copied. So the test directory that sits in the tree cannot be run from the image, and the documentation a first-time operator is told to consult is not present in the artefact they just built.

No EXPOSE, no USER, no health check on the container itself

The Dockerfile is eleven effective lines and stops at CMD [ "python", "main.py" ]. There is no EXPOSE, no USER, no HEALTHCHECK and no declared volume anywhere in it.

Two consequences follow directly. The process runs as the base image's default user, which for that Debian slim tag is root, so the gateway and whatever it pulls in run privileged by default with no instruction to change that. And the container publishes no port metadata, meaning the host side has to decide which port to map without the image telling it, which is exactly the kind of thing that ends up exposed more widely than intended.

The asymmetry is worth naming. The feature list promises a heartbeat mechanism for upstream channels, so the project is careful about endpoints dying on the other end, while the artefact it ships defines no health check for itself and runs as root.

The documentation the project points at is not inside the image

For deployment and configuration the README sends you to two addresses: a GitHub Page at rockchinq.github.io/free-one-api and a self-hosted documentation site at free-one-api.rockchin.top. That second address is also the project's homepage field, which means the canonical manual is a deployment you are expected to run yourself.

The repository does carry a docs/ directory at its root, so the source of that site is here. The Dockerfile copies neither docs/ nor either README, so the container you build carries no copy of the manual the manual tells you to go and read. Deployment details, environment variables and channel configuration are not recoverable from the image.

One more wrinkle for English readers: the file at the root is written in Chinese, and its first line links an English version at README_en.md. Both files exist in the tree.

Three releases in seven weeks, then tags stopped while the branch did not

The release history is short and front-loaded. v1.0.0-beta.4 went out on 2024-02-12, v1.0.0 on 2024-03-31 and v1.0.1 on 2024-04-02, three tags inside seven weeks. Nothing has been tagged since, while the main branch was pushed to as recently as 2026-09-25.

The README carries a version badge pointing at the repository's releases/latest page, which resolves to v1.0.1 from that April 2024 window. The Docker Hub repository named next to it, rockchin/free-one-api, has no tag or digest named anywhere in the README, so a pull gives you whatever that image was last built from.

Combine that with the unpinned reverse-engineering libraries and the reproducibility picture is thin: the same tag built on two different days pulls different adapter code, and the branch you would have to read to know what changed is far ahead of the newest tag.

Editorial conclusion

Read the terms of every upstream service before you route anything real through free-one-api. What the repository offers is an adapter layer for front ends you would otherwise drive by hand, wrapped in one OpenAI-shaped endpoint, and it is honest about being that. The load balancing, the Web UI and the heartbeat checks exist because the author considers the adapters too many and too unstable, and that sentence is the most useful line in the README. For a lab or a personal project the design fits. Before trusting it with anything else, pin the five floating reverse-engineering libraries yourself, read what the AGPL-3.0 network clause asks of you, keep the root container behind your own network policy, and remember that the last release tag is from April 2024 while the branch has moved on since.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. RockChinQ/free-one-api on GitHub