ThunderForgeVTT

Use of AI disclaimer! I am using copilot and gemini to help me build my dream. In September of 2024 I had to stop because I was out of work and needed to focus on finding a job or lose it all. In May of 2026, I am picking this back up because I landed work and can continue to follow my dream.

Note from the creator! I love what FoundrVTT and Roll20 and many others have done for us but they never fit what ive been trying to do. My goal with this passion project is to provide an environment thats agnostic if people are in person / online only / a mixed with great tools to run a game. At the end of the day, we play D&D or similar to escape reality for but a brief respite in a fantasy world and I feel a lot of the tools today get in the way of this. With this tool, I want it to help facilite the fantasy and not be an encomberence on it. I want it easy to host, easy to use, and resiliant. I have been burned too many times by dndbeyond trying to push dnd next which became 5.5 and hurting the source material. Burned with FoundryVTT major version upgrades breaking everything and in some cases major data loss. Burned by patreons for modules I have been using collecting fat paycheck but lagging so far behind on updates things get too unbearable.

Closing Notes: This project is my passion, my love for the fantasy, and im pouring my heart and soul into its existence. I apologize for being offline for so long and using AI to help me build the dream. I hope you find this project useful once I am able to finally release a working version of it. This message isnt a cry for money, stars, or anything. Its a note that this might take some time as I am only one individual and I wanted to thank you all for the patients.

An open source, self-hosted virtual tabletop. The whole app builds from source and stands up with one command.

Quick start

You need Docker with the compose plugin and about ten minutes for the first build (it compiles the Rust server and the WebAssembly engine from source).

git clone https://github.com/ThunderForgeVTT/ThunderForgeVTT.git
cd ThunderForgeVTT
docker compose up -d --build
docker compose logs app | grep /setup/

Open the setup link the last command prints. It runs the first-run wizard: your administrator account, who may join, and how the instance sends mail. After that the app is at http://localhost:42080.

The app is the only thing published on the host. Its database, object storage and mail catcher (Mailpit) stay inside the stack's own network. THUNDERFORGE_PORT moves the app, and THUNDERFORGE_PUBLIC_URL has to move with it; see the comments at the top of compose.yml for the other knobs, and for what is and is not a secret in that file.

Need the database or the Mailpit inbox on the host, for a backup or a look? Add compose.ports.yml, which publishes them on 127.0.0.1 only:

docker compose -f compose.yml -f compose.ports.yml up -d

Running your own instance has the details.

Upgrading from an earlier install? compose.yml no longer publishes PostgreSQL (42432), RustFS (42900) or Mailpit (42025, 42825), and its containers no longer have fixed names. If you relied on either, add compose.ports.yml (same port numbers, now on 127.0.0.1) and use docker compose exec <service> in place of docker exec <name>.

Useful afterwards:

• docker compose logs -f app follows the server.
• docker compose down stops the stack and keeps its data; docker compose down -v starts over from nothing.
• Lost the setup link before finishing? Set THUNDERFORGE_REGENERATE_SETUP_CODE=1, restart the app service, and read the log again.
• The only administrator lost their authenticator and their recovery codes? Set THUNDERFORGE_RESET_ADMIN_SECOND_FACTOR=<their username>, restart the app service, sign in and enrol again — then remove the variable. See docs/SECOND_FACTOR.md.

Developing

make dev runs the server and the web app on the host against a smaller dependency stack (compose.dev.yml, on the standard 5432/9000/1025/8025 ports). make container builds the app image without starting it. See docs/CONTRIBUTING.md for the test suites and AGENTS.md for the architecture.

Current Objective

Get a group playing D&D 5th edition on it end to end: sign up, build a table, put characters on a map, roll, fight, and come back next week.

Curious on whats happening

• Check out the discussions
• Take a look at project progress

What connection you need

Start from an unmetered connection of at least 50 Mbps.

That number is untested — a starting recommendation rather than a measurement, and we would rather say so than let a guess pass for a requirement. Metered, capped and mobile connections are not tested at all and are out of scope for the MVP; the client deliberately fetches world content ahead of need, which is the right trade on an unmetered link and an open question on a metered one. Holding that back is planned, not built.

If you play on something slower, metered, or on mobile data, please tell us how it went. Your experience is worth more than our estimate, and the discussions are where it can reach us.

What features the PoC should include

• Login screen, Basic authentication (argon2 for passwords)
• Landing screen, landing page should redirect to login if no auth present or else provide a list of games the user belongs to.
• Game screen, a simplified game screen with a red square and a blue square.
• Game screen controls, wasd should move the token the user has ownership over.
• Token positions should update for each user connected.

When is the PoC considered successful

• User can create a game
• User can can invite another user to join game
• Game window allows players to move tokens around
• Tokens move around with little to no lag (gauge the time delay for tic rates)

What happens after a successful PoC

Step 2

This simplified approach is designed to not be pretty for a version 0.0.1 and if the PoC is successful, the next steps are to get a pipeline running in github for deployments. The project should have a solidified deployment plan with releases configured appropriately. Ultimately, the goal is to cement the concept of easy deployments and provide indivduals the oppertunity to test ThunderForgeVTT with a well established release model.

Step 3..X

• Begin solifify data models for each object type.
• Provide a module plugin layer.
• Allow plugins to be pre-installed or dynamically installed.
• Build a basic module.
• Build a system module for D&D 5th edition based on the SRD.
• Clean up the interface.
• Add a chat, roll, etc function.
• Provide a discord hook module for a rich discord interface.
• Integrate a character creation screen
• Provide a dndbeyond integration module
• TBD

Timelines

This project is a larger project inspired by many great providers such as FoundryVTT, Roll20, and BattleMapp. The current initial release cannot be given a date becuase it takes time to create great software but rest assured this project is getting worked on daily.

Telemetry

ThunderForge reports anonymous diagnostics to its developers by default, so we hear about the bugs on instances we don't run. That covers every build, including the server image you run yourself.

• What is sent: errors with personal details stripped from them, timings, counts, the ThunderForge version, and a random id for this install.
• What is never sent: anything anyone types, rolls, names or uploads; emails, accounts, or world, character or scene ids; IP addresses; machine hostnames; cookies.
• What we add when it arrives: where it came from (our own sites, your players' browsers and your site's domain, or your server), the browser family and major version, and the country when our network edge supplies it. Our endpoint uses your IP address only in memory, to limit how fast one sender can post, and never stores or forwards it.
• Where it goes: https://telemetry.thunderforge.dev, kept for 14 days.
• Send it to your own collector instead: set OTEL_EXPORTER_OTLP_ENDPOINT for the server and THUNDERFORGE_BROWSER_TELEMETRY_ENDPOINT for browsers. Nothing then reaches us.
• Turn it off: TELEMETRY=false. Nothing is sent anywhere.

Details: docs/guides/telemetry.md.

License

ThunderForgeVTT is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-or-later). Self-hosting is always free, including for commercial/community use — the AGPL's only additional condition beyond ordinary open-source terms is that anyone who runs a modified version of this software as a network service must also make that modified source available to their users (AGPL §13). No further restriction exists.