How to run GrabBag.gg

Get a living-room game on a TV, with phones as controllers. This page is for a downloaded GrabBag.gg binary. You do not compile anything to host a room.

You are the person with the PC. Everyone else only needs a phone browser. Follow the sections in order the first time. Use the table of contents later when you only need one answer. This page is static on grabbag.gg. After you start GrabBag.gg on your PC, the same guide is also at http://127.0.0.1:8654/docs on that machine only.

What you need

A Windows computer that stays on for the whole party. That machine runs GrabBag.gg. Closing the window ends the room.
A TV, projector, or a second window for the board. That is the screen the room watches.
Phones or tablets. For a living-room night they must be on the same Wi-Fi as the computer. Guest Wi-Fi often blocks this. Use the house network. People who are not in the house follow Hosting on the internet.
An admin password you are about to pick. You will type it on setup, and once more on the first phone that should run the room.

Start the program

Double-click the GrabBag.gg program. On Windows that is usually grabbag.exe.
Leave the black console window open. That window is the server.
If Windows Firewall asks, allow GrabBag.gg on a private network.
In a browser on this computer, open the address the console printed. It looks like http://127.0.0.1:8654.

You should see either first-time setup, or the board if you already finished setup on this PC.

GrabBag.gg always uses port 8654. If another copy is already running, this one prints an error and exits. Close the other window, then start again.

127.0.0.1 only works on the machine running GrabBag.gg. Phones use a different URL. You will see it on the board, next to the QR code.

First-time setup

The first visit on this computer opens /setup.

Pick a password of at least 8 characters. This is not a player nickname. It unlocks Room settings and lets a phone claim host. There is no "forgot password" in the binary yet. Write it down.
Type it again to confirm.
Leave the other boxes on their defaults for a living-room night. Seat cap 8 is plenty. Advertised hostname should stay blank unless you follow Hosting on the internet. Logging can stay off.
Tap Finish.

You should see the board. This browser stays signed in for 30 days.

You can change the extra boxes later under Settings.

Put it on the TV

On the host computer, open http://127.0.0.1:8654/board.
Fullscreen that tab. F11 works in most browsers.
Plug the PC into the TV, or cast that window.

You should see a QR code and a join URL on the left, and empty seats in the middle. The join URL is not 127.0.0.1. That is the address phones type if they cannot scan.

The gear in the corner opens Room settings in a new tab. You need the admin password there if this browser is not already signed in from Finish.

Join from a phone

Each person opens the camera and scans the QR on the TV.
They land on a "Who are you?" screen. They can reroll the cartoon face, type a name, and tap Join.
The first joiner also sees a password field. The person who should run the room types the admin password, then Join. Everyone else leaves that field blank.

You should see cartoon faces appear in seats on the TV. The phone that typed the password gets a Host button. Later joiners do not see the password field once someone has claimed host.

If the board says Closed, new people cannot Join. Open the room from settings or from the Host panel. Closed locks the door. It does not kick people who are already in.

When every seat is taken, new joiners still arrive. They land in the audience and can get in line on the wait list. They watch. They do not take a seat until one frees up or you raise the seat cap.

To hand the room to someone else later, use Make host in settings. That person's phone then shows Take host and asks for the admin password.

On LAN the QR is the house IP. After you set a tunnel URL, the same QR is the public https:// address. See Hosting on the internet.

The games

Open Host, pick one package, then Load. The TV stays on the lobby until Start.

Apples for Humanity

One seated player is the judge each round. Everyone else fills the prompt with cards from a hand. The judge reveals the plays and picks a winner. After Load, Deck Library is on the board rail. Turn on the packs you want before Start.

White and Black is fill-in-the-blank. Oranges to Oranges is adjective and noun. Wildcard is a tiny typed-answer set. The picker can import the JSON Against Humanity dump if you want those cards. Imported cards arrive tagged sex, violence, politics, or kid friendly, so the tag filters work on them too. Bots can sit in empty chairs. How to play is on the rail after Load, and on phones during a round.

Quick Quips

Two or more seated people write lines into rotating prompts, then vote. Audience can vote if you leave those points on. After Load, Prompt Library is on the board rail. Comedy ships in the binary.

Testing

A seated list, a plunger, and latency. Use it when the host looks broken. It is not a scored party game.

Play a round

Do this from the claimed-host phone. The TV stays on the board so the room can watch.

Confirm the board is up and the room says Open.
Wait until faces are in seats. Each seated player taps Ready when they are looking at the TV.
Open Host. Pick a game, then tap Load. Load mounts that package. The TV stays on the lobby. Apples for Humanity and Quick Quips are the party games. Testing is a wiring check.
Tap Start. Start needs at least one seated player. Some games also want a minimum table size and will refuse until enough seats are filled.
Play. If you need a break, tap Pause. The round stays in memory. Resume continues it.
When the round is over, tap Stop. The lobby comes back on the TV. The same game stays selected, so you can Start again without Load.
Tap Shutdown only when you want to unload that game and pick a different one, or none at all.

After Start the TV and the seated phones switch into the game. After Stop they return to the lobby.

Auto-start is on for a new room. A full set of Ready taps starts the loaded game without a tap on Start. Turn it off in settings if you want to start by hand.

The Host button

Only the claimed-host phone shows this. It is a slide-out on that device, not a menu on every phone.

If nobody claimed host at join, the next person who still sees the password field on Join can take it. After a host exists, use Make host in settings, then Take host on that phone.

Load, Start, Pause, Resume, Stop, Shutdown

These are the round controls from the previous section. Load picks the package. Start begins play. Pause and Resume freeze and continue. Stop ends the round. Shutdown unloads the package.

Sit and Stand

Sit puts someone into a seat. Stand takes them out of a seat without kicking them from the room. Use this when you want to swap who is at the table.

Kick

Removes that person from the room right now. They have to join again. Kick does not wait for any timeout.

Room settings

Opens the same settings page as the gear on the board.

Sound on the TV

The board plays lobby music and game sound. Phones stay silent. Browsers block sound on a page until someone taps it, so the first time the board opens you see a Sound is off card in the bottom-right corner. Click Turn on sound, or press OK on a TV remote, since the button already has focus. Tapping anywhere else does not turn sound on. The card's ✕ keeps the board silent until you reload it.

The board never reloads during play, so one tap lasts the night. If the board browser crashes and reloads, the card comes back as Tap to resume sound.

To skip the tap entirely:

In Firefox, click the icon left of the address on the board tab, find Autoplay, and choose Allow Audio and Video. Firefox remembers it for this address.
On a kiosk PC, start Chromium or Chrome with --autoplay-policy=no-user-gesture-required, for example chromium --kiosk --autoplay-policy=no-user-gesture-required http://127.0.0.1:8654/board.

Levels live in Settings under Audio. The Board sound line there says whether the TV's sound is on, waiting for a tap, or turned off.

Settings

Open /settings from the board gear, the Host panel, or by typing the address. Sign in with the admin password if this tab is not already signed in.

You can ignore most of this on night one. The table is for the labels people stare at and guess wrong.

Label	What it does
Room Open or Closed	Open lets new phones Join. Closed shuts the door. People already in keep playing.
Auto-start	On for a new room. A full set of Ready taps starts the loaded game without a tap on Start. Turn it off to start by hand.
Seat cap	How many people get a face on the table. Default 8. Range 1 to 64. Audience can still watch when the table is full.
After a game	Keep seats leaves sitters in place after Stop and fills leftover seats from the wait list. Cycle seats sends the current table to the wait list and pulls the next people in line. Host Stop and a finished game use the same Stop.
Fill empty seats	Off by default. When on, a free seat during a round can go to someone waiting. When off, the current table stays frozen until Stop.
Disconnected after	Seconds of silence before GrabBag.gg treats a phone as gone. They still own the seat for a while. The face dims.
Kick timeout	While a round is running, a dropped seated phone keeps the chair. After the round, if they still have not come back, GrabBag.gg removes them once this many extra seconds have passed. Set 0 to never auto-drop.
Seat disconnected waiters	When on, someone who was only in line and then dropped off can still be pulled into a seat. Leave it off unless you mean that.
Protect host	When on, a claimed host whose phone goes quiet is not auto-removed after Kick timeout. Operator Kick still works. Default is on.
Admin-only board	When on, a random tab that opens `/board` without signing in does not see the roster. Use this if the TV URL might leak. The signed-in operator tab still works.
Auto-pause on seated disconnect	When on, a seated phone dying pauses the game so you can wait. Audience disconnects do not pause. You can Resume while they are still gone. Some games, such as Borrowed Truths, keep playing when a phone drops and ignore this. Settings says so under the switch when one is loaded.
Advertised hostname	Leave blank for a LAN party. The board then shows the IPv4 GrabBag.gg found at start. Fill this in only for a tunnel. Paste the full public URL, including `https://`. Do not add port 8654. The public side of a tunnel is HTTPS on 443. See Hosting on the internet.
Log to stdout / host.log	Stdout is the console window. host.log is a file next to the database. The Game log page is a live tail of those lines. Off is fine for a party.
Game Settings	After Load, extra checkboxes for that game appear here.
Clear game data	Wipes that game's saved options. It does not wipe seats, names, or host.log.
Audio: Master, Music, Effects	Mute button, volume slider, and percent for each layer. The TV hears a change as you drag. The ▶ buttons play a short sample on the TV. Board sound tells you whether the TV still needs a tap. See Sound on the TV.
Make host	Marks another seated person. Their phone then shows Take host and asks for the admin password.
Log out	Signs this browser out of admin. Other signed-in phones stay signed in.

Hosting on the internet

Default night is LAN. Phones and the PC share Wi-Fi. You do not buy a domain. You do not open a router port.

People off that network need a tunnel on the same PC as GrabBag.gg. The tunnel makes an outbound connection. Guests hit a public HTTPS URL. Traffic comes back to localhost:8654. The PC has to stay awake. Sleep or a closed console ends the room.

Tailscale Funnel

This is the path that does not require a purchased domain. Cost is $0. The URL is a .ts.net name. Guests do not install Tailscale.

Install Tailscale for Windows on the GrabBag.gg PC. Sign in with Google, GitHub, or Microsoft.
Start GrabBag.gg. Leave the console open.
In PowerShell, run tailscale funnel 8654. The first time, Tailscale may open a page to turn Funnel on for your account. Approve it.
Copy the printed URL. It looks like https://something.ts.net.
In GrabBag.gg settings, paste that full URL into advertised hostname. Include https://. Save.
Check the board QR. It should show the https:// address, not the LAN IP and not port 8654.

You should see phones on cellular open the same QR and land on Join.

Anyone who finds that URL can hit the same login page the TV does. Keep the admin password off the join link. Home upload speed is the real limit.

Stop Funnel when the night is over with tailscale funnel off, or quit Tailscale. Clear advertised hostname before the next LAN party so the QR goes back to the house IP.

Cloudflare

If you already have a domain on Cloudflare, a named Cloudflare Tunnel is a stable hostname you control. That product supports the live SSE GrabBag.gg uses. You still do not open a router port.

Do not use Cloudflare Quick Tunnels (trycloudflare.com, the one-command no-account URL). Cloudflare documents that those tunnels do not support SSE. The lobby and board would load, then stall.

If you quit and come back

Closing GrabBag.gg does not forget the room. The next start reloads names and seats from disk.

Start the program again.
Open the claimed-host phone. A card sits in the middle of that screen.
Tap Keep this room to keep previously connected users, or Clear room for a fresh house. Settings has the same two buttons.

Until someone taps one of those you cannot Load or Start. That pause is on purpose so a crash does not dump eight people on the floor.

Files live in the user cache, in a folder named grabbag. On Windows that is %LOCALAPPDATA%\grabbag. You will see host.sqlite, maybe host.log, and a games folder per game id. An older Hackbox install kept the same files under %LOCALAPPDATA%\hackbox. This build does not read that folder.

Phones cannot join

Work down the list. Most nights it is Wi-Fi or the wrong URL.

On LAN, confirm the phone and PC are on the same Wi-Fi. Not a guest network. Not cellular. Remote phones skip this and use the tunnel URL from Hosting on the internet.
Confirm Windows Firewall allowed GrabBag.gg on that private network.
On the phone, use the URL or QR on the board. Do not type 127.0.0.1. That address means "this device," so the phone would look for GrabBag.gg inside itself.
Confirm the board says Open.
If advertised hostname is set, it must be the full public https:// URL the tunnel printed. The QR should not show port 8654.
If you used Tailscale Funnel, confirm tailscale funnel 8654 is still running and the PC is not asleep.

Stop GrabBag.gg

Close the console window, or press Ctrl+C in it. There is no tray icon in this build.

Starting the program again brings the last room back until you Keep or Clear it.

Write a game

This guide is for running a room, not for shipping a package. Method-by-method Game and Helper docs are the game API reference.