{"id":13575535,"url":"https://github.com/claabs/epicgames-freegames-node","last_synced_at":"2025-05-14T11:11:42.305Z","repository":{"id":37869632,"uuid":"241535116","full_name":"claabs/epicgames-freegames-node","owner":"claabs","description":"Automatically login and find available free games the Epic Games Store. Sends you a prepopulated checkout link so you can complete the checkout after logging in. Supports multiple accounts, login sessions, and scheduled runs.","archived":false,"fork":false,"pushed_at":"2025-03-29T04:42:08.000Z","size":2826,"stargazers_count":1595,"open_issues_count":35,"forks_count":103,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-05-13T04:45:34.068Z","etag":null,"topics":["docker","epic-games","epic-games-client","epic-games-store","epicgames-freegames-node","free-games","reverse-engineering","self-hosted"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/charlocharlie/epicgames-freegames","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/claabs.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"custom":["https://steamcommunity.com/tradeoffer/new/?partner=39987473\u0026token=_RHKOrVn"]}},"created_at":"2020-02-19T04:47:47.000Z","updated_at":"2025-05-13T01:38:23.000Z","dependencies_parsed_at":"2023-02-18T11:48:34.456Z","dependency_job_id":"6c5aa27d-2111-4026-8b95-a328e4dc6815","html_url":"https://github.com/claabs/epicgames-freegames-node","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claabs%2Fepicgames-freegames-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claabs%2Fepicgames-freegames-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claabs%2Fepicgames-freegames-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claabs%2Fepicgames-freegames-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/claabs","download_url":"https://codeload.github.com/claabs/epicgames-freegames-node/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254129523,"owners_count":22019628,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","epic-games","epic-games-client","epic-games-store","epicgames-freegames-node","free-games","reverse-engineering","self-hosted"],"created_at":"2024-08-01T15:01:01.882Z","updated_at":"2025-05-14T11:11:40.418Z","avatar_url":"https://github.com/claabs.png","language":"TypeScript","funding_links":["https://steamcommunity.com/tradeoffer/new/?partner=39987473\u0026token=_RHKOrVn"],"categories":["TypeScript","docker","self-hosted"],"sub_categories":[],"readme":"# Epic Games Store Weekly Free Games\r\n\r\nAutomatically login and find available free games the Epic Games Store.\r\nSends you a prepopulated checkout link so you can complete the checkout after logging in.\r\nSupports multiple accounts, login sessions, and scheduled runs.\r\n\r\n## Setup\r\n\r\n### JSON Configuration\r\n\r\nThe tool can be configured with a combination of JSON and environment variables. The config file supports [JSON5](https://json5.org/) syntax (comments, trailing commas, etc). For each property, the JSON config value takes priority over the respective environment variable value.\r\n\r\nFor details on each option, its defaults, and environment variable key, see the [config documentation site](https://claabs.github.io/epicgames-freegames-node/classes/AppConfig.html).\r\n\r\nThe config file is stored in the mounted `/usr/app/config` volume and can be named `config.json` or `config.json5`.\r\n\r\n#### `config.json` or `config.json5`\r\n\r\n```jsonc\r\n{\r\n  \"runOnStartup\": true,\r\n  \"cronSchedule\": \"0 0,6,12,18 * * *\",\r\n  \"logLevel\": \"info\",\r\n  \"webPortalConfig\": {\r\n    \"baseUrl\": \"https://epic.example.com\",\r\n  },\r\n  \"accounts\": [\r\n    {\r\n      \"email\": \"example@gmail.com\",\r\n    },\r\n  ],\r\n  \"notifiers\": [\r\n    // You may configure as many of any notifier as needed\r\n    // Here are some examples of each type\r\n    {\r\n      \"type\": \"email\",\r\n      \"smtpHost\": \"smtp.gmail.com\",\r\n      \"smtpPort\": 587,\r\n      \"emailSenderAddress\": \"hello@gmail.com\",\r\n      \"emailSenderName\": \"Epic Games Captchas\",\r\n      \"emailRecipientAddress\": \"hello@gmail.com\",\r\n      \"secure\": false,\r\n      \"auth\": {\r\n          \"user\": \"hello@gmail.com\",\r\n          \"pass\": \"abc123\",\r\n      },\r\n    },\r\n    {\r\n      \"type\": \"discord\",\r\n      \"webhookUrl\": \"https://discord.com/api/webhooks/123456789123456789/A-abcdefghijklmn-abcdefghijklmnopqrst12345678-abcdefghijklmnop123456\",\r\n      // Optional list of users or roles to mention\r\n      \"mentionedUsers\": [\"914360712086843432\"],\r\n      \"mentionedRoles\": [\"734548250895319070\"],\r\n    },\r\n    {\r\n      \"type\": \"telegram\",\r\n      // Optional Custom TELEGRAM server URL\r\n      \"apiUrl\": \"https://api.telegram.org\",\r\n      \"token\": \"644739147:AAGMPo-Jz3mKRnHRTnrPEDi7jUF1vqNOD5k\",\r\n      \"chatId\": \"-987654321\",\r\n    },\r\n    {\r\n      \"type\": \"apprise\",\r\n      \"apiUrl\": \"http://192.168.1.2:8000\",\r\n      \"urls\": \"mailto://user:pass@gmail.com\",\r\n    },\r\n    {\r\n      \"type\": \"pushover\",\r\n      \"token\": \"a172fyyl9gw99p2xi16tq8hnib48p2\",\r\n      \"userKey\": \"uvgidym7l5ggpwu2r8i1oy6diaapll\",\r\n    },\r\n    {\r\n      \"type\": \"gotify\",\r\n      \"apiUrl\": \"https://gotify.net\",\r\n      \"token\": \"SnL-wAvmfo_QT\",\r\n    },\r\n    {\r\n      \"type\": \"homeassistant\",\r\n      \"instance\": \"https://homeassistant.example.com\",\r\n      \"token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c\",\r\n      \"notifyservice\": \"mobile_app_smartphone_name\",\r\n    },\r\n    {\r\n      \"type\": \"bark\",\r\n      // your bark key\r\n      \"key\": \"xxxxxxxxxxxxxxxxxxxxxx\",\r\n      // bark title, optional, default: 'epicgames-freegames'\r\n      \"title\": \"epicgames-freegames\",\r\n      // bark group, optional, default: 'epicgames-freegames'\r\n      \"group\": \"epicgames-freegames\",\r\n      // bark private service address, optional, default: 'https://api.day.app'\r\n      \"apiUrl\": \"https://api.day.app\"\r\n    },\r\n    {\r\n        \"type\": \"ntfy\",\r\n        \"webhookUrl\": \"https://ntfy.example.com/mytopic\",\r\n        \"priority\": \"urgent\",\r\n        \"token\": \"tk_mytoken\"\r\n    },\r\n    {\r\n      \"type\":\"webhook\",\r\n      //url of your webhook server\r\n      \"url\":\"https://webhook.site/my_uuid\",\r\n      //Optional headers\r\n      \"headers\": {\r\n         \"Authentication\": \"Bearer 123456\"\r\n      }\r\n    },\r\n  ],\r\n}\r\n```\r\n\r\n### Web server\r\n\r\nThis project can occasionally ask you to login via [device code authentication](https://github.com/MixV2/EpicResearch/blob/master/docs/auth/grant_types/device_code.md). Epic Games's device code session expires after 10 minutes, so this project uses a web server and redirect to prevent from sending you a new link every 10 minutes. There are two options for running the web server:\r\n\r\n#### Web server config\r\n\r\nIf you're familiar with hosting web servers and/or reverse proxies, follow this:\r\n\r\n1. Expose port 3000 in your Docker run config (e.g. `-p 81:3000` maps the host machine's port 81 to the container's port 3000)\r\n1. If you want to access the Captcha solving page from outside your network, setup any port forwarding/reverse proxy/DNS\r\n1. Set the `webPortalConfig.baseUrl` in the config\r\n\r\n#### Localtunnel setup\r\n\r\nIf you don't have the ability to port forward/reverse proxy on your network, you can still access the web server remotely by setting:\r\n\r\n```jsonc\r\n{\r\n  \"webPortalConfig\": {\r\n    \"localtunnel\": true,\r\n  },\r\n}\r\n```\r\n\r\nin your `config.json`.\r\n\r\n### Notifications\r\n\r\nEach notification method has unique setup instructions. Read its documentation ([notification methods](https://claabs.github.io/epicgames-freegames-node/classes/AppConfig.html#notifiers)) on the config site for exact details and instructions. The [example config](https://claabs.github.io/epicgames-freegames-node/classes/AppConfig.html) may also help as an example.\r\n\r\n### Testing notification and web server\r\n\r\nSince user actions may not always be required, the notification methods and web server can be manually tested. Essentially, you just need to add:\r\n\r\n```jsonc\r\n  \"testNotifiers\": true,\r\n```\r\n\r\nto the root of your `config.json`. For more details check out the [config docs](https://claabs.github.io/epicgames-freegames-node/classes/AppConfig.html#testNotifiers).\r\nNote: to optimize for standby memory usage, the web server does not run when the process is not running. The web server will only be available during a scheduled run.\r\n\r\n### Docker Configuration\r\n\r\nThis image is available from both [GitHub Container Registry](https://github.com/claabs/epicgames-freegames-node/pkgs/container/epicgames-freegames-node) and [Docker Hub](https://hub.docker.com/repository/docker/charlocharlie/epicgames-freegames):\r\n\r\n* `ghcr.io/claabs/epicgames-freegames-node:latest`\r\n* `charlocharlie/epicgames-freegames:latest`\r\n\r\nIf you're [experiencing issues with Chromium starting](https://github.com/claabs/epicgames-freegames-node/issues/164) (hangs on login/notification), you can try the Debian image:\r\n\r\n* `ghcr.io/claabs/epicgames-freegames-node:debian`\r\n* `charlocharlie/epicgames-freegames:debian`\r\n\r\nIf you are using full JSON configuration, the only remaining Docker configurables are the [port](#ports) and [volume](#volumes).\r\n\r\n#### Environment Variables\r\n\r\nMost configuration options can be set via environment variable. Look for the `env` tag in the [config docs](https://claabs.github.io/epicgames-freegames-node/classes/AppConfig.html) for each option's key.\r\n\r\nIf for whatever reason you want to change the default config directory or config file name, `CONFIG_DIR` and `CONFIG_FILE_NAME` are available as environment variables.\r\n\r\n#### Ports\r\n\r\n| Host port | Container port | Description                                                                   |\r\n|-----------|----------------|-------------------------------------------------------------------------------|\r\n| `3000`    | `3000`         | Port mapping on which the web server hosting the captcha solving page resides |\r\n\r\n#### Volumes\r\n\r\n| Host location   | Container location | Mode | Description                               |\r\n|-----------------|--------------------|------|-------------------------------------------|\r\n| `/my/host/dir/` | `/usr/app/config`  | `rw` | Location of the config and cookie file(s) |\r\n\r\n#### Memory Limit\r\n\r\nIt's recommended to add `-m 2g` as a `docker run` parameter to set a max memory usage of 2GB. The Chromium processes can sometimes run away, and without a limit your system can eventually lock up.\r\n\r\n### Docker Run\r\n\r\n#### With JSON Config\r\n\r\n`$ docker run -d -v /my/host/dir/:/usr/app/config:rw -p 3000:3000 -m 2g ghcr.io/claabs/epicgames-freegames-node:latest`\r\n\r\n#### Without JSON Config\r\n\r\nWithout JSON config, you can only configure one account.\r\n\r\n`$ docker run -d -e TZ=America/Chicago -e EMAIL=example@gmail.com -e RUN_ON_STARTUP=true -e BASE_URL=https://example.com -e SMTP_HOST=smtp.gmail.com -e SMTP_PORT=587 -e EMAIL_SENDER_ADDRESS=hello@gmail.com -e EMAIL_SENDER_NAME=\"Epic Games Captchas\" -e EMAIL_RECIPIENT_ADDRESS=hello@gmail.com -e SMTP_SECURE=true -e SMTP_USERNAME=hello@gmail.com -e SMTP_PASSWORD=abc123 -v /my/host/dir/:/usr/app/config:rw -p 3000:3000 -m 2g ghcr.io/claabs/epicgames-freegames-node:latest`\r\n\r\n### Cookie Import\r\n\r\nIf you're experiencing issues logging in with device code auth, you can import cookies for a temporary session.\r\n\r\n1. Setup the container per the below instructions\r\n1. In your web browser, log in to the Epic Games Store with \"Remember me\" checked.\r\n1. Install the [EditThisCookie](http://www.editthiscookie.com/) browser extension.\r\n1. While viewing the Epic Games Store page, open the EditThisCookie extension window, change the URL to `https://www.epicgames.com/id`, and click the export button:\r\n![EditThisCookie export button](https://github.com/claabs/epicgames-freegames-node/blob/master/img/edit-this-cookie.png?raw=true)\r\n1. In your mounted `./config` folder, create `\u003cemail_address\u003e-cookies.json` (e.g. `me@example.com-cookies.json`), and paste in your cookies.\r\n1. Start the container and the cookies will automatically be converted to a new format.\r\n\r\n#### Cookie Import Notes\r\n\r\n* If you click \"Log Out\" on the browser session you copied the cookies from, the container may break.\r\n* If you have the container scheduled regularly, it should automatically refresh the cookies and keep you logged in for some time.\r\n\r\n## Running without Docker\r\n\r\nIf for some reason you don't want to use Docker to run this tool you can run it from source by cloning this repo and installing Node.js.\r\n\r\n1. Get this repo from Github\r\n    * Clone using git (recommended): `git clone https://github.com/claabs/epicgames-freegames-node.git`\r\n    * Or download and unpack ZIP archive: [epicgames-freegames-node](https://github.com/claabs/epicgames-freegames-node/archive/master.zip)\r\n1. Create `config` folder in the cloned/unpacked directory\r\n1. Create [JSON configuration](#json-configuration)\r\n1. [Install Node.js 18](https://nodejs.org/) or higher\r\n1. Install Node.js dependencies\r\n    * Start terminal and navigate to cloned/unpacked directory\r\n    * Run `npm i`\r\n1. Start application: `npm run start`\r\n1. To update when using Git:\r\n    * `git pull`\r\n    * `npm i`\r\n\r\n## Miscellaneous\r\n\r\n### v4 to v5 Migration\r\n\r\nIn v5, several options have been added or removed. The added/removed options should not affect existing v4 configs, but may need to change your `config.json` for a stable solution.\r\n\r\n#### Changed\r\n\r\n* `cronSchedule`: The default was changed to every six hours. You should change your cron schedule to run more often than every 8 hours, as the device code auth refresh token expires after 8 hours.\r\n\r\n#### Removed\r\n\r\n* `account.password`: login credentials are no longer used\r\n* `account.totp`: login credentials are no longer used\r\n* `noHumanErrorHelp`: purchase is no longer automated\r\n* `hcaptchaAccessibilityUrl`: was deprecated in v4\r\n* `email`: was deprecated in v4, use `notifiers` with `\"type\": \"email\"`\r\n* `baseUrl`: was deprecated in v4, use `webPortalConfig.baseUrl`\r\n* `onlyWeekly`: was deprecated in v4, use `searchStrategy`\r\n\r\n### Thanks\r\n\r\nThanks to [epicgames-weekly-freegames](https://github.com/Ricardo-Osorio/epicgames-weekly-freegames) for the inspiration.\r\n\r\nThanks to [EpicResearch](https://github.com/MixV2/EpicResearch) for the documentation that made device code auth possible.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclaabs%2Fepicgames-freegames-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclaabs%2Fepicgames-freegames-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclaabs%2Fepicgames-freegames-node/lists"}