Keeps one PKForge Bank in sync across your devices, such as phones and handhelds. Every device keeps its full Bank and works offline; this server is where their changes meet. Run it yourself with Docker.
Bank Sync is proposed for PKForge in a pull request. Until it is part of a PKForge release, build the app
from the pr/bank-sync branch of YoruDev-Ryland/PKForge.
The server stores Pokémon as opaque bytes and never edits them. Conflicts (the same Pokémon edited on two devices) are reported to the app, which asks you what to keep.
- To run it: Docker with Compose. Images are published for x64 and arm64 (such as a Raspberry Pi 4 or 5).
- To build or work on it: the .NET 10 SDK and Node.js 24 (see CONTRIBUTING.md).
-
Get the compose file in a folder of its own:
mkdir pkforge-sync && cd pkforge-sync curl -LO https://raw.githubusercontent.com/YoruDev-Ryland/pkforge-sync-server/main/docker-compose.yml
In
docker-compose.yml, setPUBLIC_URLto the address your devices use to reach this machine, for examplehttp://<your-server-ip>:8080. -
Start it:
docker compose up -d
-
In PKForge, open Bank Sync, choose Connect to a server, enter the same address and create your account. The first account on a server is its admin and can always sign up.
-
Add more devices by signing in on them, or with Add a device on a signed-in device (QR code or 8-character code, valid 5 minutes).
Security note: on a fresh server with no accounts, the first person to register can always do so (even with
ALLOW_REGISTRATION=false) and becomes the admin. Create your own account (in the app, or withdocker exec pkforge-sync create-user you@example.com --admin) before the server is reachable by anyone else.
To keep the data in a host folder instead of a Docker volume, mount it at /data, for example
./data:/data. The folder can be new or empty: the container creates and takes ownership of it on start.
docker compose pull && docker compose up -dYour data stays in the pkforge-sync-data volume, and the database upgrades itself on start.
PKHeX is included as a git submodule (external/PKHeX), so clone with --recurse-submodules (or run
git submodule update --init in an existing clone); the build fails without it.
git clone --recurse-submodules https://github.com/YoruDev-Ryland/pkforge-sync-server.git
cd pkforge-sync-serverIn docker-compose.yml, replace the image: line with build: ., then run docker compose up -d --build.
Set these as environment variables (all optional).
| Variable | Default | What it does |
|---|---|---|
PUBLIC_URL |
http://localhost:8080 |
Address devices and email links use to reach the server |
ALLOW_REGISTRATION |
false |
Let anyone with the address create an account (the first account always can); once an admin changes it on the web Bank's Account page, that choice wins |
WEB_ROOT |
wwwroot beside the app |
Folder with the built web app; set it only when running from source |
DATA_DIR |
/data in the Docker image; data (relative to the working directory) otherwise |
Where the SQLite database and Pokémon data live |
PUID, PGID |
1654 |
Who owns the data folder and runs the server; set them to your user's ids to own the files on the host |
DATABASE_PROVIDER |
sqlite |
sqlite or postgres |
DATABASE_CONNECTION |
SQLite file in DATA_DIR |
Database connection string (required for PostgreSQL) |
REQUIRE_EMAIL_VERIFICATION |
false |
Block syncing until the account's email is confirmed |
TRUST_FORWARDED_HEADERS |
false |
Trust X-Forwarded-For/-Proto; only behind your own reverse proxy |
RELEASED_RETENTION_DAYS |
30 |
How long a released Pokémon can be restored from the web Bank's Recently released (0 = releases are final) |
SERVER_NAME |
PKForge Sync |
The name apps and the web Bank show for this server (at most 60 characters) |
SMTP_HOST |
(none) | Mail server for verification and password-reset emails; no host means no email |
SMTP_PORT |
587 |
Mail server port (465 uses TLS from the start) |
SMTP_USERNAME, SMTP_PASSWORD |
(none) | Mail server login |
SMTP_FROM |
PKForge Sync <no-reply@localhost> |
Sender of the emails |
Every setting can also be given in ASP.NET Core form, such as Sync__AllowRegistration=true.
The server also hosts a browser version of PKForge's Bank, served at the server's own address (for
example http://localhost:8080/). Sign in with your app account or with a pairing code from
Add a device. The Docker image includes it; nothing extra to set up.
To work on it, run the server on port 5099 and start the dev server (port 5173), which proxies /v1 and
/pkhex to it:
git submodule update --init # PKHeX is needed to build the server and for the art under /pkhex
ASPNETCORE_URLS=http://localhost:5099 dotnet run --project src/PKForge.Sync.Server --no-launch-profile
# in another terminal
cd web
npm ci
npm run devBefore sending changes, run both type checks and the tests: npm run check, npm run check:tests,
npm test and, with Playwright browsers installed (npx playwright install), npm run e2e. npm run build writes the app to web/dist; dotnet publish does this for you
(skip it with -p:SkipWebBuild=true). To serve a local build from dotnet run, point the server at it:
WEB_ROOT=$(pwd)/web/dist dotnet run --project src/PKForge.Sync.Server.
docker exec pkforge-sync list-users
docker exec pkforge-sync create-user misty@example.com # prints a password
docker exec pkforge-sync create-user brock@example.com --admin
docker exec pkforge-sync reset-password ash@example.com # prints a new password
docker exec pkforge-sync force-resync --all # after restoring a backupWithout email configured, reset-password is how a forgotten password is recovered.
Inside your home network plain HTTP is fine. To sync from outside, put the server behind a reverse proxy
that provides HTTPS (Caddy, Traefik, nginx, or a tunnel such as Tailscale), set PUBLIC_URL to the HTTPS
address, and set TRUST_FORWARDED_HEADERS=true so login rate limits see real client addresses. Never
expose plain HTTP to the internet: device keys and passwords would travel unencrypted.
The web Bank keeps one long-lived request open (GET /v1/sync/events, server-sent events) so changes from
other devices show up at once. The server marks it X-Accel-Buffering: no and sends a keep-alive every
25 seconds (Sync__EventHeartbeatSeconds); a proxy that buffers responses or closes idle connections sooner
than that only slows updates down to the page's regular check every two minutes.
Everything lives in the pkforge-sync-data volume. Stop the container and copy the volume, or take a live
copy of the database with sqlite3 /data/sync.db ".backup /data/backup.db" and copy /data/blobs with it.
After restoring a backup, run docker exec pkforge-sync force-resync --all. Every device then re-downloads
the Bank at its next sync and uploads whatever the backup was missing, so nothing a device still holds is lost.
Run one server per database. Sync writes are serialized inside the process, so several instances sharing one database could interleave writes to the same Bank.
environment:
DATABASE_PROVIDER: "postgres"
DATABASE_CONNECTION: "Host=db;Database=pkforge_sync;Username=pkforge;Password=secret"The server creates the database and its tables on first start.
Deployments can register an IAccountWritePolicy to make accounts read-only, e.g. for quotas: a refused push
gets 403 writes_disabled with the policy's reason, while reading and downloading keep working.
dotnet test tests/PKForge.Sync.Server.Tests # Docker must be running for the PostgreSQL tests
dotnet run --project src/PKForge.Sync.ServerSee CONTRIBUTING.md for the full set of checks.
Database changes need a migration for each provider:
cd src/PKForge.Sync.Server
dotnet ef migrations add <Name> --context SqliteSyncDbContext --output-dir Data/Migrations/Sqlite
dotnet ef migrations add <Name> --context PostgresSyncDbContext --output-dir Data/Migrations/PostgresCopyright (C) 2026 PKForge Sync contributors
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General
Public License as published by the Free Software Foundation, either version 3 of the License, or (at your
option) any later version (SPDX: GPL-3.0-or-later). See LICENSE for the full text.
Third-party components (PKHeX.Core and its images, PokeAPI data, fonts and packages) are listed with their licenses in THIRD-PARTY-NOTICES.md.
This project is not affiliated with, endorsed by or sponsored by Nintendo, Creatures Inc., GAME FREAK inc. or The Pokémon Company. Pokémon and Pokémon character names are trademarks of their respective owners. No game artwork is stored in this repository; the sprites, ball icons and box wallpapers the web Bank shows are copied from PKHeX at build time.