martinbjeldbak/acestream-http-proxy
martinbjeldbak/acestream-http-proxy has 109 GitHub stars and 20 forks. GitHot measured 0 stars in 24 hours and 0 in 7 days. Last checked 2026-11-16 19:39 UTC. Last push 2026-11-08.
Measured star growth
- in 24h
- 0
- in 7 days
- 0
- in 15 days
- Update delayed
- in 1 month
- Update delayed
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
Stream AceStream sources on macOS and other systems without needing to install AceStream player
Developer ToolsREADME.md
OriginalAceStream HTTP Proxy
This Docker image runs the AceStream Engine and exposes its HTTP API.
As a result, you will be able to watch AceStreams over HLS or MPEG-TS, without needing to install the AceStream player or any other dependencies locally.
This is especially useful for Desktop and NAS usage for anyone who wants to tune in to AceStream channels, and who don't want to go through the trouble of installing AceStream and its dependencies natively.
Note: ARM-based CPUs are not currently supported, see issues #5 and #13.
Usage
Ensure you have Docker installed and running. You can then pull down and run the container as shown below.
docker run -t -p 6878:6878 ghcr.io/martinbjeldbak/acestream-http-proxy
You are then able to access AceStreams by pointing your favorite media player (VLC, IINA, etc.) to either of the below URLs, depending on the desired streaming protocol.
For HLS:
http://127.0.0.1:6878/ace/manifest.m3u8?id=dd1e67078381739d14beca697356ab76d49d1a2
For MPEG-TS:
http://127.0.0.1:6878/ace/getstream?id=dd1e67078381739d14beca697356ab76d49d1a2
where dd1e67078381739d14beca697356ab76d49d1a2d is the ID of the AceStream channel.
This image can also be deployed to a server, where it can proxy AceStream
content over HTTP. To accept connections from other hosts on your network (LAN
or VPN), set ALLOW_REMOTE_ACCESS=yes; see Remote access.
You can also run it using Compose with
---
services:
acestream-http-proxy:
image: ghcr.io/martinbjeldbak/acestream-http-proxy
container_name: acestream-http-proxy
ports:
- 6878:6878
environment:
- ALLOW_REMOTE_ACCESS=no # change to "yes" to accept connections from other hosts
volumes:
- acestream-data:/home/appuser/.ACEStream # engine database and cache
volumes:
acestream-data:
for an example, see the compose.yaml file in this repository.
Configuration
Remote access
ALLOW_REMOTE_ACCESS must be exactly yes or no (lowercase); any other
value, including true or YES, is treated as no.
The AceStream engine has no authentication. Enabling remote access lets any host that can reach port 6878 start streams through your connection, so only enable it on a trusted network, restrict the published port to your LAN or VPN interface, and never expose it directly to the internet. It is not required for reverse proxy setups.
Custom engine flags
Any engine command line option can be passed as a
space-separated EXTRA_FLAGS value:
environment:
- EXTRA_FLAGS=--use-internal-buffering 1 --cache-limit 4
Do not add quotes inside the value (EXTRA_FLAGS='--cache-limit 4' passes a
literal ' to the engine and the container exits with No such option).
Invalid flags or values make the container exit immediately rather than being
silently ignored.
Flags are appended after the image defaults (--cache-dir … --cache-limit 1 --client-console), so they override the same option set by default, and after
--bind-all. If you change --http-port, publish that port instead of 6878.
The authoritative list of options is the one the bundled engine prints:
docker run --rm --entrypoint /app/start-engine \
ghcr.io/martinbjeldbak/acestream-http-proxy --client-console --help
Persistence
The engine writes its database, cache and logs to /home/appuser/.ACEStream
(owned by UID/GID 1000), which is the only writable path apart from /.cache.
Mount a volume there to keep the engine state across container restarts;
compose.yaml uses a tmpfs for it by default.
Ports
| Port | Protocol | Purpose |
|---|---|---|
6878 |
TCP | HTTP API: HLS, MPEG-TS and /webui/api/service |
62062 |
TCP | Engine API, fixed |
8621 |
TCP, UDP | Peer-to-peer service, fixed |
| random high | UDP | BitTorrent peer sockets, re-picked on every container start |
Only 6878 is required to watch streams, as the engine connects out to trackers
and peers by itself. Publishing 62062 and 8621 can help other peers connect
in to you, but the random UDP ports cannot be published reliably. The
acestream.upnp|Failed to init port forward log line is expected in a container
and harmless.
Reverse proxy
The engine answers with absolute URLs built from the request's Host
header: GET /ace/manifest.m3u8?id=… returns a 302 to
http://<Host header>/ace/m/<hash>/<token>.m3u8, and the playlist and segment
URLs use the same base. It takes that base from the Host header, port
included, so the proxy only has to forward Host unchanged.
Two consequences:
- If the forwarded
Hosthas no port, the engine appends its own (6878), e.g.http://example.com:6878/…. nginx's$hoststrips the port, so use$http_hostinstead. - The scheme is always
http://;X-Forwarded-Protois ignored. Terminate TLS at the proxy and let the player follow thehttp://URLs on the same hostname.
Serve the engine on its own subdomain: the URLs are rooted at /ace/ and
/content/, so a subpath such as /acestream/ would require rewriting the
playlist body.
nginx
location / {
proxy_pass http://acestream-http-proxy:6878; # container name, not 127.0.0.1
proxy_set_header Host $http_host; # not $host: the port is required
proxy_http_version 1.1;
proxy_buffering off; # live HLS / MPEG-TS
proxy_read_timeout 1h;
}
Caddy
Caddy forwards Host unchanged, so no header overrides are needed:
ace.example.com {
reverse_proxy acestream-http-proxy:6878
}
Do not set header_up Host {upstream_hostport}, as the engine would then
redirect to the container's internal hostname.
Authentication middleware
Media players (VLC, IINA, mpv, Infuse, Jellyfin) do not send browser session
cookies, so site-wide authentication such as forward_auth (Authelia, SWAG)
redirects every playlist and segment request to a login page. Either protect
only the entry point and bypass authentication on the tokenised paths, or keep
the engine reachable from your LAN/VPN only:
| Path | Note |
|---|---|
/ace/manifest.m3u8, /ace/getstream |
contains the content ID |
/ace/m/<hash>/<token>.m3u8 |
playlist, per-session token |
/ace/r/<hash>/<token>, /content/<hash>/… |
MPEG-TS redirect and stream |
/ace/c/<hash>/<n>.ts |
HLS segments |
Buffering and caching
The engine has no "buffer a number of seconds" setting: it emits HLS from a
sliding window of roughly 5–7 second segments (#EXT-X-TARGETDURATION:7), and
the playback API exposes no latency parameter. What can be tuned is the
engine's cache, which tolerates slow peers without changing latency, and the
player's read-ahead, which absorbs jitter:
mpv --cache=yes --demuxer-max-bytes=256M --demuxer-readahead-secs=60 \
'http://127.0.0.1:6878/ace/manifest.m3u8?id=<content-id>'
vlc --network-caching=15000 \
'http://127.0.0.1:6878/ace/manifest.m3u8?id=<content-id>'
Engine-side options include --cache-limit (disk cache ceiling in GB, 1 by
default), --cache-max-bytes, --cache-auto and --use-internal-buffering.
To find out whether a stalled stream is the engine or the player, request the
JSON form to get a stat_url, then poll it while the player is stuck:
curl 'http://127.0.0.1:6878/ace/manifest.m3u8?id=<content-id>&format=json'
curl 'http://127.0.0.1:6878/ace/stat/<infohash>/<token>'
If downloaded keeps climbing while playback is frozen, the player stopped
reading; if the session disappears or stays in prebuf, the source or peers are
the problem.
Running through a VPN
An HTTP proxy is not sufficient for routing all AceStream traffic: the engine
honours HTTP_PROXY/HTTPS_PROXY for its HTTP control traffic only, and there
is no SOCKS support. Peer traffic goes out directly, so a proxy does not hide
your IP from the swarm. To route everything through a VPN, share the VPN
container's network namespace instead:
services:
gluetun:
image: qmcgaw/gluetun
cap_add:
- NET_ADMIN
ports:
- 6878:6878 # published on the VPN container, not on acestream
environment:
- FIREWALL_INPUT_PORTS=6878
# VPN_SERVICE_PROVIDER=...
acestream-http-proxy:
image: ghcr.io/martinbjeldbak/acestream-http-proxy
network_mode: service:gluetun
depends_on:
- gluetun
environment:
- ALLOW_REMOTE_ACCESS=yes
volumes:
- acestream-data:/home/appuser/.ACEStream
volumes:
acestream-data:
Ports must be published on the VPN container: with network_mode: service:gluetun, a ports: block on acestream-http-proxy has no effect.
Troubleshooting
The engine is chatty at startup, and most of what it prints is harmless. These lines appear on a healthy container:
ls: cannot access '/dev/disk/by-id/'— the engine probes disk serials for a machine fingerprint; containers have no/dev/disk.acestream.upnp|Failed to init port forward— no UPnP/NAT-PMP in a bridged container; see Ports.TrafficStatsSender,UpdateNotificationsTaskandPluginsContainererrors — anonymous usage statistics, the notification feed and plugin updates are unreachable from inside the container.
If streams never start, the container most likely has no outbound network. Check that the engine itself is up:
curl -i 'http://127.0.0.1:6878/webui/api/service?method=get_version'
and that a container can reach the internet:
docker run --rm alpine sh -c 'ping -c3 1.1.1.1 && wget -qO- https://ifconfig.me'
If that fails, look at DNS (a container resolv.conf pointing at the host's
127.0.0.53 stub cannot work), a host firewall dropping forwarded traffic, and
rootless container networking.
Contributing
First of all, thanks!
Ensure you have a container runtime with Compose support (e.g. Docker with the
Compose plugin, or Podman with podman-compose), as outlined
above. This image is simply a simplified wrapper around the
AceStream HTTP API in order to make it more user friendly to get
running. All options supported by the AceStream Engine are supported in this
project. Any contributions to support more configuration is greatly
appreciated!
Dockerfile steps are roughly guided by https://wiki.acestream.media/Install_Ubuntu.
For a list of AceStream versions, see here: https://docs.acestream.net/products/#linux
For convenience of easy image rebuilding, this repository contains a
compose.yaml file. You can then build & run the
image locally by running the following command:
docker compose up --build
(or podman-compose up --build if you're using Podman)
The image will now be running with port 6878 published; see Ports for details. See the AceStream developer documentation for command line arguments and debugging.