steam-idle-bot 1.0.1

Farm Steam playtime and trading-card drops on autopilot. Steam Idle Bot syncs your library, idles only the games that still have cards to drop, and remembers what's already finished — so every run scans less and starts faster. Live terminal dashboard, web UI, two interchangeable idling backends with automatic fallback.

Why it's different

Most idlers blindly run every game forever. Steam Idle Bot is accurate and self-pruning:

Quick start

# 1. Install uv (if needed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Clone & install
git clone https://github.com/bernardopg/steam-idler-python.git
cd steam-idler-python
uv sync

# 3. Configure (never commit the filled .env)
cp .env.example .env
#    edit .env → USERNAME, PASSWORD, and ideally STEAM_API_KEY

# 4. Preview without contacting Steam
./run.sh --dry-run

# 5. Run it — terminal, or ./run-web.sh for the web UI
./run.sh

💡 A free Steam Web API key unlocks automatic library sync and badge-based filtering. Without it the bot still runs — it just can't filter as precisely.

How it works

The orchestrator wires a configuration layer to a swappable idling backend and three card services, then drives a refresh loop that tracks drops as they drain.

Game selection is a funnel — each stage narrows the set, capped at Steam's hard limit of 32:

Common commands

./run.sh                              # run normally (terminal)
./run.sh --dry-run                    # print config + chosen games, no Steam contact
./run.sh --no-trading-cards           # skip trading-card filtering
./run.sh --max-games 10               # cap idled games
./run.sh --refresh-interval-seconds 300   # re-run selection every 5 min
./run.sh --checkpoint-minutes 5 --duration-minutes 25  # timed run + JSON/MD checkpoints
./run.sh --stop-app-ids "570,730"     # stop steam-utility idles for those App IDs and exit
STEAM_IDLE_SKIP_SYNC=1 ./run.sh       # skip the runner's preflight uv sync
STEAM_IDLE_RUNNER_VERBOSE=1 ./run.sh  # show uv sync output while preparing the environment

./run.sh keeps the Python bot out of a shell pipeline so Ctrl+C reaches it directly, writes bot output to logs/runs/run_*.log, and prints a short startup/exit banner. By default it clears stale exported Steam Idle Bot environment overrides so .env wins; set STEAM_IDLE_PRESERVE_ENV=1 when you intentionally want exported variables to override .env.

Full flag and setting reference: USAGE guide.

Configuration

Settings come from environment variables / a .env file (copy .env.example). The two required values are USERNAME and PASSWORD; everything else has sane defaults.

🔐 Card-drop filtering needs an authenticated web:community session. See the authentication & accuracy guide.

Documentation

Requirements

• Python 3.12+ — managed for you by uv
• A Steam account with games that have trading cards
• Steam Web API key (recommended) — library sync + badge data
• For drop filtering — an authenticated Steam web session

Contributing

Contributions welcome in both languages. Run uv run ruff check . && uv run mypy src && uv run pytest -q before opening a PR. See the developer guides: 🇺🇸 English · 🇧🇷 Português. The prioritized roadmap lives in BACKLOG.md.

License

MIT — see LICENSE. Not affiliated with Valve. Use responsibly and follow Steam's Terms of Service.