> For the complete documentation index, see [llms.txt](https://maxlware.gitbook.io/moeworth-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://maxlware.gitbook.io/moeworth-docs/minecraft/zyntra/playit.gg/en.md). # EN ## playit.gg connection This guide explains how the playit.gg tunnel works in Zyntra, how to get a key, and how to troubleshoot issues. {% hint style="info" %} Versions up to and including [1.1.0-beta](https://modrinth.com/mod/zyntra/version/1.1.0-alpha) do not include the playit tunnel. {% endhint %} {% hint style="danger" %} Version [1.1.1-release](https://modrinth.com/mod/zyntra/version/1.1.1-release) may have issues creating the tunnel. We recommend using 1.B and 2 instead. {% endhint %} *** ### 1. Get a playit.gg key You can use either method. #### Method A - Automatic (recommended) 1. Start the server. The dashboard shows **"⏳ Initializing tunnel..."** while the playit.gg agent downloads and starts. 2. As soon as a link is available, the button changes to **"πŸ”— Connect playit.gg"**. 3. Click it. Your browser opens a playit.gg page. Guest accounts work, and **no credit card is required**. 4. Confirm the link with the **"Claim"** button on the website. 5. The first time only, playit.gg redirects you to its dashboard to create a tunnel. Choose **"Create Tunnel" β†’ type "Minecraft Java"**. The local port is filled in automatically. 6. Once confirmed, the button changes to **"βœ“ playit.gg connected"** β€” the key is saved, and you will never need to click it again for this server. #### Method B - Manual (if you already have a playit.gg account or agent) 1. Go to [playit.gg/account/agents](https://playit.gg/account/agents) while signed in. 2. Copy the `secret_key` for the agent you want to use, or create a new one. 3. In Zyntra, open the server **Options** tab and paste the key into the **"Playit Key"** field. 4. Click **Save Options**. {% hint style="info" %} Restart the server. The key is applied only when the tunnel starts again, not live. {% endhint %} *** ### 2. Downloading the playit-agent agent Zyntra does not ship a playit.gg SDK. When a server starts its tunnel for the first time, it automatically downloads the official `playit-agent` executable and caches it. * **Cache location**: `/playit/bin/playit-agent(.exe)` * **Per-server working directory**: contains `playit.toml` and the local secret key: `/playit//` * **Download strategy**, in order: 1. `https://builds.playit.gg//`: the official CDN, where `` is inferred automatically from the latest GitHub release. 2. If that CDN does not respond, Zyntra falls back to the assets attached to the latest GitHub release at `github.com/playit-cloud/playit-agent/releases/latest`. {% hint style="warning" %} The download does not run again if the file already exists in the cache. Delete it manually to force a new attempt. This is useful after a fix. {% endhint %} *** ### 3. When it does not work Every step is logged with the `[Zyntra]` prefix in the server console, in the dashboard **Console** tab, or in the Minecraft client logs. Here is how to read the most common messages. #### `Impossible d'interroger l'API GitHub` * **Likely cause**: your network blocks `api.github.com`, or your firewall or antivirus filters it. * **Solution**: check your connection, or allow `api.github.com` and `builds.playit.gg` in your firewall or antivirus. #### `GitHub API releases/latest β†’ HTTP 403` ou `429` * **Cause**: GitHub rate limiting applies 60 requests per hour per IP without authentication. This happens if you restart several times in a row, or if your IP is shared through CGNAT, a VPN, or a company network. * **Solution**: wait about one hour, or use **Manual Method B** (Β§1), which does not depend on automatic download. You will then need to install `playit-agent` yourself once. See Β§4. #### `Essai builds.playit.gg : ... β†’ HTTP 404` * **Cause**: the filename guessed for your OS and architecture does not exist for that version number. playit.gg has already changed its naming convention several times. * **Solution**: check the previous log line, `Latest detected playit-agent version: X.X.X`, then open `https://builds.playit.gg/X.X.X/` in your browser to inspect the files that are actually available. Report it so the filename can be added to the candidate list. #### `Aucun binaire playit-agent trouvΓ© pour ...` * **Cause**: every attempt failed, including builds.playit.gg and GitHub assets. * **Immediate solution**: manual installation. See Β§4. #### The button stays stuck on "⏳ Initializing tunnel..." * **Cause**: either the download is still in progress, which is normal during the first few seconds, or the agent started but has not yet printed a claim link in its logs. * **Solution**: check the server console. If there is no `[Zyntra][playit]` line after 30 seconds, the process probably crashed at startup. Check the errors right before it. Otherwise, wait. On a slow connection, the very first startup can take a minute because it includes the download and first connection. #### The tunnel reconnects in a loop (`Reconnexion Γ  playit.gg dans 5000 ms`) * **Cause**: either the binary could not be downloaded, see the errors above, or the agent starts and then crashes because of an invalid key, a local port conflict, or a similar issue. * **Solution**: read the previous line, `[Zyntra] Erreur de tunnel playit.gg : ...` β€” it contains the exact error message. *** ### 4. Manual playit-agent installation If automatic download keeps failing because of a restrictive network or persistent rate limiting: 1. Download `playit-agent` yourself from [playit.gg/download](https://playit.gg/download), or directly from `builds.playit.gg` if you know the version. 2. Rename the file: * Windows β†’ `playit-agent.exe` * Linux/macOS β†’ `playit-agent` 3. Place it in `/playit/bin/`. 4. On Linux or macOS, make it executable with `chmod +x playit-agent`. 5. Restart the server β€” Zyntra detects the existing binary and does not try to download it again. {% hint style="info" %} On Linux, you can also install playit through your distribution package manager, such as apt, rpm, or apk. See the instructions on playit.gg/download. Then point the cached `playit-agent.exe` or `playit-agent` file to the system binary with a symlink or a copy. {% endhint %} *** ### 5. Support If you run into issues, contact the team here: * Email: * Discord: