Skip to content
HimanMPublic

About

An app that allows you to AFK mine timed Twitch drops, with automatic drop claiming and channel switching.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

1,031 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

DropForge icon

DropForge

A desktop, terminal, and self-hosted Twitch drops miner maintained by HimanM.

Latest release Build status Docker image status Latest container image

DropForge discovers eligible Twitch campaigns, selects a live channel, advances watch progress without playing video, switches channels when needed, and claims supported rewards. Use the desktop GUI, Linux Web UI, terminal UI, portable CLI, or Docker image.

Important

Run only one DropForge instance per Twitch account. Running Twitch video or another miner with the same account can make progress reporting unreliable.

Table of contents

Features

  • Tracks active, upcoming, completed, excluded, and unlinked campaigns.
  • Prioritizes selected games and automatically switches to eligible live channels.
  • Supports allowed-channel campaigns and optional ACL bypass for incorrect Twitch channel eligibility data.
  • Can farm unlinked drops when Twitch reports the account-link state incorrectly.
  • Can farm free watch-time badges while priority work is idle. Subscription badges with 0/0 minutes are skipped.
  • Preserves Twitch login, settings, web credentials, and recovery data across updates.
  • Sends formatted Discord webhook notifications for selected priority categories.
  • Includes campaign, category, reward, progress, and channel artwork in the Web UI.
  • Recovers from transient GraphQL, integrity-token, and network failures without routine manual restarts.

Choose an interface

Interface Best for Platforms Start here
Desktop GUI Regular desktop use Windows, macOS, Linux Download a release
Web UI Always-on home server or VPS Linux, Docker One-command install
TUI Full-screen terminal use Linux, macOS python tdminer.py tui
CLI SSH, Termux, and simple terminals Windows, Linux, macOS, Android python tdminer.py cli
Docker Isolated self-hosting Linux amd64 and arm64 Compose setup

Desktop GUI

Download the newest archive from GitHub Releases, extract it, and run DropForge.

Platform Release asset
Windows DropForge.Windows.zip
macOS DropForge.MacOS.zip
Linux AppImage DropForge.Linux.AppImage-<arch>.zip
Linux portable GUI DropForge.Linux.PyInstaller-<arch>.zip

At the Twitch login prompt, choose Import auth token and paste the auth-token cookie from a signed-in Twitch browser. DropForge saves it in cookies.jar beside the portable app data.

Linux Web UI

Install

Run the installer as your normal Linux user:

curl -fsSL https://raw.githubusercontent.com/HimanM/DropForge/main/scripts/install.sh | sh

Choose Web UI when prompted. The installer:

  1. Installs the required system and Python packages.
  2. Installs DropForge under ~/.local/share/tdminer.
  3. Creates and starts tdminer-web.service.
  4. Prints the access URL, admin password, and recovery code in a clearly marked block.
  5. Stores persistent data under ~/.local/share/tdminer/data.

The default address is http://127.0.0.1:17473. Save the generated admin password and recovery code before closing the terminal.

To choose the first admin password yourself, use at least 12 characters:

curl -fsSL https://raw.githubusercontent.com/HimanM/DropForge/main/scripts/install.sh | \
  TDMINER_ADMIN_PASSWORD='replace-with-a-strong-password' sh

If tdminer-web is not found after installation, add the default launcher directory to your shell path:

printf '\nexport PATH="$HOME/.local/bin:$PATH"\n' >> ~/.profile
. ~/.profile

Connect Twitch

For small Linux servers, choose Device login in Overview or Settings. Open the activation link on any phone or computer, enter the displayed code, and authorize Twitch for TV. You can close that browser afterward: no Chromium, desktop helper, VPN exit node, or ongoing connection to your PC is needed by the server.

This is an optional, web-only login method. Campaign discovery uses the existing public catalogue; Twitch remains authoritative for watch progress and claim confirmation. Desktop GUI/TUI login is unchanged. Device credentials are stored separately in web-device-session.json, while browser cookies and settings are preserved across updates. The server checks the device token at startup and hourly and retains it through temporary connection failures.

Authentication problems appear in a persistent banner on every web page, including a quick activation link when login is needed. In Settings → Discord notifications, enable your webhook and Twitch authentication alerts to receive server-wide expiry, verification, prolonged connection-failure, and recovery messages. Repeated retries are deduplicated; temporary failures do not erase the saved session. The webhook does not receive tokens, cookies, or activation codes.

Session lifetime: the tested TV client advertises no scheduled expiry, but Twitch can revoke it. Automatic refresh is not guaranteed (Twitch currently requires a client secret for this client's refresh token). If activation is required again, open DropForge and approve a fresh code on any device. Reset Twitch login removes only the active login method's saved session; it does not revoke your Twitch website login.

Web installs no longer install a browser by default. To use browser-token import instead, install Chrome/Chromium and Xvfb yourself, or rerun the installer with TDMINER_INSTALL_BROWSER=1. Existing browsers are not removed. Docker's standard image still bundles Chromium for browser-token compatibility; device mode does not launch it.

Browser-token import remains available and never asks for your Twitch password:

  1. Sign in at twitch.tv on a desktop browser.
  2. Open the browser developer tools.
  3. Open Application or Storage, then Cookies, then https://www.twitch.tv.
  4. Copy only the value of the cookie named auth-token.
  5. In DropForge, choose Import auth token, or run:
tdminer-web import-twitch-token

Treat the token like a password. The command briefly stops the miner, validates the session, saves it, and restores the service. Copying the same token to another installation is possible, but only one miner should run for that account.

Remote access

Localhost is the recommended bind address. Tailscale Serve provides private HTTPS access to devices on your tailnet:

tailscale serve --bg http://127.0.0.1:17473

To expose DropForge directly to the LAN, reinstall or update with 0.0.0.0:

curl -fsSL https://raw.githubusercontent.com/HimanM/DropForge/main/scripts/install.sh | \
  TDMINER_HOST=0.0.0.0 sh

Then open http://SERVER_IP:17473. This is plain HTTP and listens on every reachable interface. Use it only on a trusted network or behind a trusted HTTPS reverse proxy.

To use another port:

curl -fsSL https://raw.githubusercontent.com/HimanM/DropForge/main/scripts/install.sh | \
  TDMINER_PORT=28461 sh

Manage the service

Command Action
tdminer-web status Show service status
tdminer-web start Start the Web UI and miner controller
tdminer-web stop Stop the Web UI and mining
tdminer-web restart Restart the service
tdminer-web logs Follow service logs
tdminer-web reset-password Set a new admin password and revoke browser sessions
tdminer-web import-twitch-token Replace the saved Twitch session

The installer creates and enables tdminer-web.service automatically. Fresh web installs use browser-free device activation; updates retain the existing login method and session. Miner messages and server errors go to the system journal:

sudo systemctl status tdminer-web.service --no-pager
sudo journalctl -u tdminer-web.service -f
# Recent service logs:
sudo journalctl -u tdminer-web.service -n 200 --no-pager

Logging out of the website clears only the web browser session. It does not stop the miner or sign the saved Twitch session out.

Update

Run the same installer command again:

curl -fsSL https://raw.githubusercontent.com/HimanM/DropForge/main/scripts/install.sh | sh

The installer remembers the selected interface and bind address. It stages the new release, keeps persistent data, restarts the service, and restores the previous release if startup fails.

To switch an existing Linux installation between interfaces:

# Web UI
curl -fsSL https://raw.githubusercontent.com/HimanM/DropForge/main/scripts/install.sh | TDMINER_MODE=web sh

# Portable CLI
curl -fsSL https://raw.githubusercontent.com/HimanM/DropForge/main/scripts/install.sh | TDMINER_MODE=cli sh

Docker

The latest multi-architecture image is published for linux/amd64 and linux/arm64:

ghcr.io/himanm/dropforge:latest

The package and available tags are listed on the DropForge container page.

Docker Compose

mkdir -p dropforge && cd dropforge
curl -fsSLO https://raw.githubusercontent.com/HimanM/DropForge/main/docker-compose.yml
docker compose up -d
docker compose logs dropforge

The Compose file publishes 127.0.0.1:17473, restarts the container unless stopped, and stores state in the dropforge-data volume. The first logs contain the generated admin password and recovery code.

Set the first admin password yourself if needed:

TDMINER_ADMIN_PASSWORD='replace-with-a-strong-password' docker compose up -d

Update the container without losing settings or sessions:

docker compose pull
docker compose up -d

Useful commands:

docker compose ps
docker compose logs -f dropforge
docker compose restart dropforge
docker compose stop
docker compose down

docker compose down keeps the named data volume. docker compose down -v permanently deletes it.

TUI and CLI

On Linux, the one-command installer can install the CLI directly:

curl -fsSL https://raw.githubusercontent.com/HimanM/DropForge/main/scripts/install.sh | TDMINER_MODE=cli sh
tdminer --import-token
tdminer

The installed Linux launcher uses the portable CLI. For the Textual TUI, run from source or download DropForge.TUI.<platform>.zip from GitHub Releases:

python tdminer.py tui

Force the portable CLI from source:

python tdminer.py cli

Add verbose file logging when troubleshooting:

python tdminer.py cli --log -vv

The CLI supports slash-command autocomplete. Type /help for the complete command list.

Command Action
/reload Refresh inventory and campaigns
/switch <channel> Switch to a listed channel
/priority add <game> Add a priority game
/priority remove <game> Remove a priority game
/exclude add <game> Exclude a game
/exclude remove <game> Remove an exclusion
/mode <mode> Select priority-only, ending-soonest, or low-availability
/farm-unlinked on|off Toggle unlinked-drop farming in priority-only mode
/badges on|off Include badge and emote campaigns in normal farming
/auto-badges on|off Farm free watch-time badges while priority work is idle
/channels, /drops, /settings, /logs Change CLI view
/quit Exit DropForge

Termux installs from source because Android does not run glibc Linux binaries:

pkg install python clang curl tar
curl -fsSL https://raw.githubusercontent.com/HimanM/DropForge/main/scripts/install.sh | sh
tdminer --import-token
tdminer

Settings

  • Priority mode controls campaign order. Priority list only limits farming to selected games.
  • Farm unlinked drops is available only in priority-list-only mode.
  • Trust allowed channels follows Twitch campaign ACLs. Disable it only when Twitch shows a valid allowed channel but incorrectly marks it as ineligible.
  • Badge and emote drops includes those rewards in normal campaign selection.
  • Auto-farm free badges runs only when priority work is idle and skips subscription badges.
  • Skip drops that cannot finish (off by default) skips a reward when its remaining watch time exceeds the time before the earlier of its own or its campaign's expiry. It still farms other finishable rewards and never blocks completed claims. GUI: Advanced settings; TUI: Settings; CLI: /skip-unfinishable on|off; web: Settings → Mining. The estimate assumes one watch minute per real minute and can be affected by delayed Twitch progress.
  • Priority and excluded games are managed in the dedicated Games page or the desktop Settings tab.
  • Use Save and reload after selection changes so the active inventory is rebuilt immediately.
  • Discord Drop notifications follow priority categories. With Auto-farm free badges enabled, earned free badges and badge-fallback status are also reported outside the priority list; subscription badges and unrelated item Drops stay filtered out. Earned Drops and badges controls completion notifications.
  • In the web Campaigns page, choose Free badges to browse watch-time badges across categories without changing mining priorities. Zero-minute subscription badges are excluded, and Finished shows earned badges even when their campaign still has other rewards.
  • Discord reward messages show the supplied reward image prominently, with category art as a thumbnail and a direct reward-image link.
  • Web logs show newest messages first, with text search, event-category filters and an Errors filter. Categories are best-effort labels for the original miner text; the buffer remains the latest 200 messages.

Some campaigns require a linked game account. Manage links at Twitch Drops campaigns.

Data and backups

Installation Persistent data
Linux installer ~/.local/share/tdminer/data
Docker Compose dropforge-data volume mounted at /data
Portable desktop build Beside the executable or app bundle
Source run Repository working directory unless TDMINER_DATA_DIR is set

Important files include:

Path Purpose
cookies.jar Twitch session, keep private
web-device-session.json Web-only device session; keep private, survives updates
cookies.jar.backup Last recoverable Twitch session
settings.json Miner, priority, webhook, and interface settings
web-auth.sqlite3 Hashed web credentials and browser sessions
cache/ Cached campaign and image data
log.txt File log when logging is enabled

Back up the data directory or Docker volume while DropForge is stopped. Updates do not replace these files.

Security

  • Web passwords and recovery codes are salted and hashed with scrypt.
  • Web session cookies are opaque and HttpOnly.
  • The Twitch auth-token, cookies.jar, web-device-session.json, recovery code, and Discord webhook URL are secrets.
  • Website logout revokes that browser session but leaves the miner and Twitch session running.
  • Changing the admin password revokes all active web browser sessions.
  • Prefer localhost with Tailscale Serve or an HTTPS reverse proxy over direct public exposure.
  • Never post logs or settings until secrets have been removed.

Uninstall

Stop and remove a Linux Web UI installation while keeping data for a later reinstall:

sudo systemctl disable --now tdminer-web.service
sudo rm -f /etc/systemd/system/tdminer-web.service
sudo systemctl daemon-reload
rm -f ~/.local/bin/tdminer-web ~/.local/bin/tdminer
rm -rf ~/.local/share/tdminer/releases ~/.local/share/tdminer/current
rm -f ~/.local/share/tdminer/install-mode ~/.local/share/tdminer/web-host

If the installer opened UFW port 17473, remove the rule:

sudo ufw delete allow 17473/tcp

Delete all settings, web credentials, and the Twitch session only when you no longer need them:

rm -rf ~/.local/share/tdminer

This last command cannot be undone. Adjust the paths if TDMINER_INSTALL_DIR or TDMINER_APP_DIR was customized.

Run from source

Python 3.10 or newer is required.

Linux and macOS

git clone https://github.com/HimanM/DropForge.git
cd DropForge
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements-tui.txt
python tdminer.py --import-token
python tdminer.py tui

Windows PowerShell

git clone https://github.com/HimanM/DropForge.git
Set-Location DropForge
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python main.py

For the portable Windows CLI, install requirements-tui.txt and run python tdminer.py cli.

Build and deployment

GitHub Actions builds the Windows and macOS GUI, Linux GUI and AppImage packages for x86_64 and aarch64, terminal binaries, install script artifact, and the GHCR image. See DEPLOY.md for source-build prerequisites and packaging details.

Credits

DropForge is maintained by HimanM.

The original Twitch Drops Miner was created by DevilXD with contributions from its community.

About

An app that allows you to AFK mine timed Twitch drops, with automatic drop claiming and channel switching.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages