# iptv-proxy: putting an IPTV provider behind your own address and credentials

> iptv-proxy is a Go reverse proxy that takes an M3U/M3U8 playlist or an Xtream Codes account and serves the same channels from your own address with a username and password you choose. It is one binary or one container, has no database and no web configuration, and can also present channels to Plex, Jellyfin or Channels DVR as an HDHomeRun tuner.

**pierre-emmanuelJ/iptv-proxy** — IPTV reverse proxy for M3U/M3U8 playlists and Xtream Codes accounts, with HLS. One binary or Docker container.

- Repository: https://github.com/pierre-emmanuelJ/iptv-proxy
- Stars: 733 · Forks: 207
- Language: Go
- License: GPL-3.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/pierre-emmanuelj-iptv-proxy

## One address in front of a provider login

The idea is stated in a single paragraph of the README. You give iptv-proxy an M3U/M3U8 playlist or an Xtream Codes account, and it serves the same channels, movies and series from your own address, with a user and a password you choose. The point is that your players, whether TiviMate, IPTV Smarters, VLC or Kodi, talk to the proxy and never see the provider's address or credentials. The README lists the situations this serves: sharing IPTV at home without handing out the provider's login, putting a provider behind your own domain with HTTPS or VPN, and giving every device one address that does not change. Behind that sits a hard operational constraint that shapes everything else. The proxy is stateful in the sense that it must be able to reach the provider, and it holds the provider's credentials, so it becomes a component in your security boundary rather than a convenience wrapper. The design choice of no database and no web configuration interface keeps that component small: a read-only status page shows what is being watched, and everything else is a flag, an environment variable or a configuration file line.

## Running the container with an M3U playlist

The quick start uses Docker, with 192.168.1.10 standing in for the machine running the proxy and family / choose-a-password for the credentials you give your players. The command passes the provider playlist address, the hostname your players reach, the credentials and the Gin release mode:

```bash
docker run -d --name iptv-proxy -p 8080:8080 \
  -e M3U_URL="http://provider.example:8080/playlist.m3u" \
  -e PROXY_HOSTNAME=192.168.1.10 \
  -e PROXY_USER=family \
  -e PROXY_PASSWORD=choose-a-password \
  -e GIN_MODE=release \
  pierro777/iptv-proxy:latest
```

Your player is then pointed at the proxy's own playlist endpoint:

```
http://192.168.1.10:8080/iptv.m3u?username=family&password=choose-a-password
```

The README also shows how to check the same address from a terminal before involving any player at all:

```bash
curl "http://192.168.1.10:8080/iptv.m3u?username=family&password=choose-a-password"
```

That curl is the first thing worth running on any install, because it tells you whether the upstream playlist was fetched and rewritten at all before you start debugging a player. If the playlist is a local file rather than an address, the README shows mounting it read only and pointing M3U_URL at the mounted path.

## The Xtream Codes path and the passthrough mode

An Xtream Codes provider is configured with three variables instead of one, and the player is pointed at the proxy as if the proxy were the provider:

```
Server:   http://192.168.1.10:8080
Username: family
Password: choose-a-password
```

A player that only accepts a playlist can still use the usual Xtream addresses, with the guide served from the proxy as well:

```
Playlist: http://192.168.1.10:8080/get.php?username=family&password=choose-a-password&type=m3u_plus&output=ts
Guide:    http://192.168.1.10:8080/xmltv.php?username=family&password=choose-a-password
```

The option table in the README describes the passthrough flag, XTREAM_PASSTHROUGH, defaulting to false: players log in with their own account of the provider. That is a different security posture from the default, where the proxy holds one provider credential and issues its own to players. In passthrough mode the proxy still sits in the path and still rewrites the addresses, but each viewer authenticates against the provider with their own account, which matters for a shared household with separate subscriptions. The same table shows that every option can be given three ways, as a flag, as an environment variable using the flag name in upper case with underscores instead of dashes, or as a line in the configuration file, with a flag beating the variable and the variable beating the file.

## Media servers see a tuner, and HLS channels need the ffmpeg build

The feature that reaches beyond IPTV players is the HDHomeRun tuner. The README states that media servers such as Plex, Jellyfin, Emby and Channels DVR can see the live channels as an HDHomeRun TV tuner, with their guide. That changes the use case from watching on a phone to integrating live TV into a DVR or a home theatre setup. There is a catch attached to it. Channels your provider offers only as HLS will not be handled by the basic image, and the README says to take the ffmpeg variant in that case, and that nothing else needs it. Each tag has such a variant, named latest-ffmpeg, v4-ffmpeg and v4.7.0-ffmpeg among others, and it is about 140 MB larger. So the image choice is not a preference but a functional decision tied to how your provider delivers a given channel. The rest of the tag matrix is built around version pinning, with latest plus a version tag such as v4.7.1, v4.7 or v4, and v3 for the 3.x line, and since v3.12.0 the images work on amd64 and on ARM including Raspberry Pi and Apple silicon, with Docker pulling the right one for the machine.

## Building the binary and running it without Docker

The binary route exists for people who would rather not run a container. The README says to download the archive for your system, covering Linux, macOS and Windows on amd64 and arm64, with .deb and .rpm packages, from the releases page, or to build it with Go 1.27 or later:

```bash
git clone https://github.com/pierre-emmanuelJ/iptv-proxy.git
cd iptv-proxy
go build -o iptv-proxy .
```

Running the binary takes the same settings as flags rather than variables:

```bash
GIN_MODE=release ./iptv-proxy \
  --m3u-url "http://provider.example:8080/playlist.m3u" \
  --hostname 192.168.1.10 \
  --user family \
  --password choose-a-password
```

One practical warning from the README is worth repeating: quote the playlist address, because it usually contains a question mark and an ampersand. The module file confirms the Go baseline, declaring go 1.27, and the direct dependencies are gin for the HTTP layer, gin-contrib/cors, cobra for the command line and viper for configuration, which matches the flag, environment variable and file precedence described in the options table.

## Where the proxy stops being the right answer

Several limits follow from what the project is and is not. First, the alternative for a single viewer on a single network is the provider's own application or playlist URL, with the proxy adding a second hop and a second credential to manage for no gain in that case. Second, the proxy is not transcoding on demand for ordinary channels: if your provider only offers some channels as HLS, you need the larger ffmpeg image, so the set it and forget it deployment has a condition attached. Third, the read-only status page means there is no web interface to configure anything, which is a deliberate simplification, but it also means there is no interface for reviewing who watched what beyond the live view. Fourth, the option table in the README ends partway through, with the --https entry visible and the table cut off in the documentation available here, so options beyond that point are not something to rely on without checking the full list in the repository. And fifth, there is no database, which is a strength for deployment and a limit for anything that needs history.

## Release cadence and what the licence means

The project ships often. The three most recent releases are v4.7.1, v4.7.0 and v4.6.0, all published on 2026-10-05 within a few hours of each other, and the last push to the repository was on 2026-10-05 as well. The CI workflow badge and the changelog at the repository root give you the detail on what changed, and the repository carries a goreleaser configuration alongside a Dockerfile and a docker-compose.yml, which is how the multi-architecture images and the .deb and .rpm packages are produced. The licence is GPL-3.0, and that has a direct consequence for the intended use. The proxy sits between your provider and your household, often on a small home server, and the copyleft terms matter if you modify it and distribute the modified version, and they are a factor for a business that intends to offer the proxy as a service to people outside the household. The repository also carries SECURITY.md, CONTRIBUTING.md and a code of conduct, so there is a place to report an issue and a documented way to contribute, but the licence is the thing to read before you build on top of it.

## Conclusion

iptv-proxy fits a household or small group that wants one stable address for its players, wants the provider's login to stay on one machine, or wants live channels visible to Plex, Jellyfin, Emby or Channels DVR as a tuner. It is the wrong tool for a single device on a single network, since running the provider's own app directly gives the same channels with less machinery, and it is the wrong tool if your provider already serves HDHomeRun properly or if you need transcoding for channels that only exist as HLS unless you accept the ffmpeg image, which the README says is about 140 MB larger. Verify first that your provider's playlist or Xtream base URL is reachable from the proxy machine, decide whether the proxy holds the provider credentials or each player logs in itself with the passthrough mode, and check the GPL-3.0 licence against your distribution plans before you expose the container to anyone outside your network.

## FAQ

### What does iptv-proxy do with my IPTV provider credentials?

By default the proxy holds the provider playlist or Xtream Codes account and issues its own credentials to your players, which never see the provider's address or credentials. The XTREAM_PASSTHROUGH option, false by default, changes that so players log in with their own provider account.

### How do I configure iptv-proxy?

Every option can be a flag, an environment variable or a line in the configuration file, with the flag winning over the variable and the variable over the file. The README notes there is no database and nothing to configure in a web interface, only a read-only status page showing what is being watched.

### Can Plex or Jellyfin see my channels through iptv-proxy?

Yes. The README states that media servers such as Plex, Jellyfin, Emby and Channels DVR can see the live channels as an HDHomeRun TV tuner with their guide. Channels your provider offers only as HLS need the ffmpeg image variant, which is about 140 MB larger.

### Does iptv-proxy run on a Raspberry Pi or Apple silicon?

Yes. Since v3.12.0 the Docker images work on amd64 and on ARM, including Raspberry Pi and Apple silicon, and Docker pulls the image matching your machine. The -amd64 and -arm64 tags still name one architecture explicitly.

### Can I run iptv-proxy without Docker?

Yes. The README says to download the archive for your system from the releases page, covering Linux, macOS and Windows on amd64 and arm64 with .deb and .rpm packages, or to build it with Go 1.27 or later using go build -o iptv-proxy .

## Sources

- [Issues](https://github.com/pierre-emmanuelJ/iptv-proxy/issues)
- [License: GPL-3.0](https://github.com/pierre-emmanuelJ/iptv-proxy/blob/master/LICENSE)
- [pierre-emmanuelJ/iptv-proxy on GitHub](https://github.com/pierre-emmanuelJ/iptv-proxy)
- [README](https://github.com/pierre-emmanuelJ/iptv-proxy/blob/master/README.md)
- [Releases](https://github.com/pierre-emmanuelJ/iptv-proxy/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/pierre-emmanuelj-iptv-proxy