SteamSelfGifter

SteamSelfGifter is an automated bot for entering Steam game giveaways on SteamGifts.com. It features a modern web interface for managing your giveaway entries, tracking wins, and configuring automation settings.

Features

• Web Dashboard: Modern React-based UI for monitoring and control
• Wishlist Integration: Automatically enters giveaways for games on your Steam wishlist
• DLC Support: Optional support for DLC giveaways
• Smart Auto-join: Automatically enters giveaways based on customizable criteria:
  • Minimum price threshold
  • Minimum review score
  • Minimum number of reviews
• Safety Detection: Detects and avoids trap/scam giveaways with background safety checks
• Win Tracking: Track your wins and win rate statistics
• Real-time Updates: WebSocket-based live notifications
• Analytics Dashboard: View entry statistics and trends
• Activity Logs: View detailed logs of all bot activity

Screenshots

Browse and filter giveaways — by review score, win chance, time remaining, and safety, with live entry counts and win odds on every card:

Analytics — entry statistics, giveaway coverage, and win rate at a glance:

Quick Start

Docker (Recommended)

# Using the pre-built image from GitHub Container Registry
docker run -d \
  --name steamselfgifter \
  -p 8080:80 \
  -v steamselfgifter-data:/config \
  ghcr.io/kernelcoffee/steamselfgifter:latest

# Access the web interface at http://localhost:8080

Image tags

Tag	Meaning
latest	Last tagged release (stable channel)
X.Y.Z, X.Y, X	Specific release versions
nightly	Latest master build, also rebuilt daily for base-image updates
<sha>	Exact commit builds

Releases are cut by pushing a git tag: git tag v2.0.0 && git push origin v2.0.0. Images are only published after the full test suite passes.

Or with Docker Compose:

# Clone the repository
git clone https://github.com/kernelcoffee/SteamSelfGifter.git
cd SteamSelfGifter

# Pulls the published image and starts it
docker compose up -d

# ...or build from source instead of pulling
docker compose up -d --build

# Access the web interface at http://localhost:8080

Note: after pulling a new image or rebuilding, use docker compose up -d --force-recreate so the running container is actually replaced (some engines, e.g. podman-compose, keep the old container otherwise).

Running the backend as a non-root user (Docker)

By default everything in the container runs as root, which is fine for rootless podman (container-root maps to your own host user). On real Docker, set PUID/PGID (see the commented lines in docker-compose.yml) to run the backend as that uid/gid — /config is chown'd accordingly on startup so the database and logs end up owned by your host user instead of root.

Development with Docker

docker-compose.dev.yml runs both halves from source with auto-reload (uvicorn --reload, Vite HMR) — the production docker-compose.yml is untouched:

docker compose -f docker-compose.dev.yml up

# Frontend (proxies /api and /ws): http://localhost:5173
# Backend API directly:            http://localhost:8000

Dev data lives in ./config-dev (separate from the production ./config); dependencies are cached in named volumes, so only the first start installs.

Manual Installation

Backend

cd backend
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

# Start the backend
cd src
uvicorn api.main:app --host 0.0.0.0 --port 8000

Frontend

cd frontend
npm install
npm run dev  # Development server at http://localhost:5173

Configuration

1. Open the web interface
2. Go to Settings
3. Enter your SteamGifts PHPSESSID (see below)
4. Configure your preferences:
   • Enable/disable automation
   • Enable/disable DLC giveaways
   • Set auto-join criteria (min price, score, reviews)
   • Enable safety check for trap detection

How to get your PHPSESSID

1. Sign in to SteamGifts
2. Open your browser's developer tools (F12)
3. Go to the Application tab (Chrome) or Storage tab (Firefox)
4. Find Cookies → www.steamgifts.com
5. Copy the PHPSESSID value
6. Paste it in the Settings page

Security

The web interface and API have no authentication — anyone who can reach the port controls the bot and can read your SteamGifts session. The app is designed to run on a trusted home network (LAN) only:

• Don't expose the port to the internet. If you need remote access, put it behind a reverse proxy with authentication (Authelia, basic auth, ...) or access it over a VPN/tunnel (WireGuard, Tailscale, ...).
• Your PHPSESSID is stored in plain text in the SQLite database inside /config (or ./config with the provided compose file). Treat that directory as a secret: don't commit it, don't share it.
• The PHPSESSID cookie is your logged-in SteamGifts session. Anyone who obtains it can act as you on SteamGifts until it expires.

Architecture

SteamSelfGifter/
├── backend/              # FastAPI REST API + SQLite
│   ├── src/
│   │   ├── api/          # REST API endpoints
│   │   ├── core/         # Configuration, logging, exceptions
│   │   ├── db/           # Database session management
│   │   ├── models/       # SQLAlchemy ORM models
│   │   ├── repositories/ # Data access layer
│   │   ├── services/     # Business logic
│   │   ├── utils/        # SteamGifts/Steam API clients
│   │   └── workers/      # Background job scheduler
│   └── tests/            # Test suite (pytest)
├── frontend/             # React + TypeScript + Vite + TailwindCSS
│   └── src/
│       ├── components/   # Reusable UI components
│       ├── hooks/        # React Query hooks
│       ├── pages/        # Page components
│       └── services/     # API client
├── docs/                 # Documentation
├── Dockerfile            # Multi-stage single-container build
└── docker-compose.yml    # Docker deployment configuration

API Documentation

Once the backend is running, visit:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

When running via Docker, the API is available at:

• http://localhost:8080/api/v1/

Development

Running Tests

# Backend tests
cd backend
pip install -e ".[test]"
pytest

# Frontend build/lint
cd frontend
npm run lint
npm run build

Database Migrations

The project uses Alembic for database migrations. Migrations run automatically on startup.

The SQLite database lives in the runtime data directory: /config inside the container (mounted from ./config by the compose file), or ./data relative to the working directory when running the backend locally.

# Create a new migration after model changes
cd backend/src
alembic revision --autogenerate -m "description"

# Apply migrations manually
alembic upgrade head

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

This bot is for educational purposes only. Please ensure you comply with SteamGifts' terms of service and use this tool responsibly.