Epic Weekly Free Games Helper

🇺🇸 English | 🇨🇳 中文文档

Epic Weekly Free Games Helper is built for regular users. It runs on GitHub Actions by default, so you do not need a server, a permanently running local machine, or any extra deployment. If you have a GitHub account, you can get started by following the setup steps below.

The key point is simple: it is fully free. In the common setup, you do not need to pay for a server or keep a local machine online. GitHub Actions is enough to run the weekly claim flow automatically.

The project is built upon community open-source solutions and incorporates GLM multimodal support. Its core objective is to ensure the stability of auto-login, captcha recognition, and checkout processes. Compared to Gemini, the GLM setup process is more straightforward, and its free quota is sufficient for regular automated execution.

If you choose the GLM route, make sure the related Zhipu account has already passed real-name verification, or the API may remain unavailable.

2026.4.28: Some users reported that the API can be called without real-name verification, so if you encounter unavailability, please check this setting.

If you do not have a Zhipu account yet, you can register through this invite link: BigModel.cn invite link.

Community discussion and feedback are welcome on LINUX DO.

If the project worked for you, feel free to leave a message here too: 🎉 Success Stories / Successful runs.

If you run into an error, please feel free to open an Issue. The choice is always yours, and I respect that; still, if you are willing to leave feedback instead of deleting the repo and walking away, those real reports and user experiences directly help improve the project and keep this effort moving forward.

The GLM path is primarily recommended for the following advantages:

• Less configuration: in most cases you only need GLM_API_KEY and GLM_MODEL.
• Lower cost: the free quota of glm-4.6v is often enough for the weekly-claim use case.
• More stable for this project: glm-4.6v-flash can occasionally fail under load with "the current model is too busy", so glm-4.6v is the safer default.
• Better fit for users in China: you do not need to solve Google AI Studio registration or availability first.
• Capability already validated: login captcha, checkout verification, drag, click, and multi-select challenges have all been verified in real runs.

• Your Epic account email and password.
• Epic account 2FA must be disabled (email, SMS, or authenticator app).
• A GLM account with GLM_API_KEY prepared for captcha solving.

Basic configuration and execution steps:

After forking, open the Actions page in your fork, enter Epic Awesome Gamer (Scheduled), and click Enable workflow once, or GitHub will not activate the scheduled run for that fork.

• Fork the repo to your own GitHub account.
• Open Actions and enable the workflow named Epic Awesome Gamer (Scheduled).

Go to Settings -> Secrets and variables -> Actions.

Required in all cases:

If you use GLM, start with this set:

If you plan to use GLM_API_KEY, make sure the related Zhipu account has already passed real-name verification, or the API may remain unavailable.

Configuration page example:

If you use the official Gemini API, use this set:

If you use a Gemini-compatible relay such as AiHubMix, use this set:

Notes:

• The current codebase supports both the official Gemini API and Gemini-compatible relays such as AiHubMix.
• The variable name is GEMINI_BASE_URL, not GEMINI_BASE_MODEL.
• When you use the official Gemini API, leave GEMINI_BASE_URL empty so the SDK uses Google's default endpoint.
• Only set GEMINI_BASE_URL when you use AiHubMix or another Gemini-compatible relay.
• For GLM, glm-4.6v is the recommended starting value; glm-4.6v-flash can fail during peak traffic.
• For Gemini / AiHubMix, GEMINI_MODEL=gemini-2.5-pro is the recommended starting value.
• If CHALLENGE_CLASSIFIER_MODEL, IMAGE_CLASSIFIER_MODEL, SPATIAL_POINT_REASONER_MODEL, and SPATIAL_PATH_REASONER_MODEL are left empty, they automatically follow the active provider default, meaning GLM_MODEL or GEMINI_MODEL.
• If you do not want to split models by task yet, leave all four override fields empty.
• The GLM path does not require an extra GEMINI_API_KEY.

If you do want to override those four model fields explicitly, use values like these:

• Open the Actions page.
• Select Epic Awesome Gamer (Scheduled).
• Click Run workflow.

When the run succeeds, the logs usually contain lines like:

Login success
Right account validation success
Authentication completed
Starting free games collection process
All week-free games are already in the library

Example log with warnings but final success:

If the logs show repeated retries and you cancel the run manually, like the example below, that still does not prove the automation had already failed. In many cases it simply had not finished yet:

Each GitHub Actions run attempts to upload the artifacts below. GitHub only shows artifacts that actually contain files, so different users may see only some of them. That is normal.

| Artifact | Content | When it usually appears | | --- | --- | | epic-logs-<run_id> | Runtime logs | Almost every run | | epic-runtime-<run_id> | promotions.json, purchase_debug screenshots, and debug text | Common after the run reaches freebie discovery, product pages, or checkout | | epic-screenshots-<run_id> | Extra screenshots for login failures, risk-control pages, and auth debugging | Only when the login, risk-control, or auth flow saved screenshots |

Download location:

1. Open the specific Actions run page.
2. Scroll to the bottom.
3. Find Artifacts.
4. Download the zip files.

What to inspect first:

These files are generated and uploaded after each GitHub Actions run. They are not fixed directories pre-shipped in the repository root.

If you need to open an issue, do not paste only a short log excerpt.

• If your fork is public, the Actions run URL is usually enough because maintainers can inspect the run page directly.
• If your fork is private, you must upload the artifact zip files that were actually generated for that run. Maintainers cannot access private Actions pages or private run artifacts.

If you want to reproduce the same entrypoint locally, use the repository's built-in one-shot run path:

1. Copy .env.example to .env
2. Fill in your own account and model configuration
3. Run uv sync --group dev
4. Run ENABLE_APSCHEDULER=false uv run app/deploy.py

.env, .venv, and app/volumes/ are already ignored by .gitignore, so they will not be committed to GitHub.

Cause: GitHub Actions environments use shared cloud IPs, which easily trigger Epic's strict risk control, causing fluctuations in captcha success rates. This is an expected behavioral pattern.

This is usually not a model-provider issue. It is an Epic account state issue. Some accounts are redirected after login to a page like /id/login/correction/privacy-policy, which requires a one-time privacy-policy confirmation.

The fix is simple: sign in to Epic once in a normal browser, complete that confirmation page manually, and then rerun the workflow.

This means Epic two-factor authentication is still enabled on the account. The current project does not support Epic email / SMS / authenticator-based 2FA, so you need to disable it in the Epic account settings before rerunning the workflow.

If you see signals like these, treat them as “Epic 2FA is still enabled”:

• errors.com.epicgames.common.two_factor_authentication.required
• Two-Factor authentication required to process request
• A redirect to /id/login/mfa

How to fix it:

1. Sign in to the Epic account in a normal browser
2. Open the account security settings page
3. Click Remove for every enabled verification method
4. Make sure email, SMS, authenticator, and any other Epic 2FA methods are all disabled
5. Rerun the workflow

Reference page:

This is not automatically a bug. It is Epic's extra human-verification step during checkout.

Description: This is an additional security verification step during checkout. The workflow already contains automation logic for this stage, so seeing the prompt below does not automatically mean the script is broken.

This usually happens when the product officially supports Windows while GitHub Actions is running on Linux.

By itself, this does not always mean the claim failed. The current automation will try to click Continue on that dialog and keep going.

Historically, the common root causes were:

If you do not want to use GitHub Actions, you can also run the project on your own server, NAS, or local Docker environment.

git clone https://github.com/Ronchy2000/epic-freebies-helper.git
cd epic-freebies-helper

The main entry is docker/docker-compose.yaml.

GLM example:

environment:
  - LLM_PROVIDER=glm
  - GLM_API_KEY=your_glm_key
  - GLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4
  - GLM_MODEL=glm-4.6v

Official Gemini API example:

environment:
  - LLM_PROVIDER=gemini
  - GEMINI_API_KEY=your_gemini_key
  - GEMINI_BASE_URL=
  - GEMINI_MODEL=gemini-2.5-pro

AiHubMix example:

environment:
  - LLM_PROVIDER=gemini
  - GEMINI_API_KEY=your_key
  - GEMINI_BASE_URL=https://aihubmix.com
  - GEMINI_MODEL=gemini-2.5-pro

docker compose up -d --build

If you want the project structure, adapter details, and developer-oriented troubleshooting notes, continue with:

• Advanced Guide
• GitHub Actions Guide
• Development Log (2026-04-22)
• Maintenance Log

This project is based on QIN2DIM/epic-awesome-gamer and also references 10000ge10000/epic-kiosk:

Thanks to the original authors, maintainers, and the community work that made this project possible.

• This project is for learning and research around automation flows.
• Automated actions may violate the target platform's terms of service. Evaluate the risk yourself.
• You are responsible for any consequences caused by using this project.

The continuous improvement of this project relies not only on code iterations, but heavily on every user who, upon encountering an error, chose not to give up, but patiently submitted a complete error report.

The resolution of many edge cases did not stem from unilateral developer testing, but was built upon the detailed logs, screenshots, and reproduction steps actively provided by the community. It is this authentic diagnostic data that enabled obscure and hidden issues to be accurately isolated and resolved.

We extend our most genuine gratitude to everyone who has submitted feedback. The time you invested and the real-world data you shared have steadily illuminated the blind spots in development, allowing this project to mature and genuinely benefit a wider audience.