How to Use


Follow these steps to synchronize your Agent interface with Night City.

1. Preparation & Installation

  • Ensure you have the Cyberpunk Red module installed in Foundry VTT.
  • Install the Cyberpunk Red Agent Bridge module in Foundry VTT by adding this manifest URL in the module installer:
    https://gitlab.com/surrealtech/Cyberpunk-Red-Agent-Bridge/-/raw/main/module.json
  • Sign up and log in to this app. Your personal data is only used for authentication.

Quick Connect: QR Pairing

The idea here is to minimise the connection errors. There is much better error handling on the Agent side so any troubleshooting should be easier. With that said:

There are two QR codes, GM (for setup) and Player (for connection):

  • Foundry Setup Code (GM only) — In Settings, enter your Foundry URL and generate an API Key — saving creates your session automatically. Hit Get Foundry Setup Code and type the short code (e.g. KX7M-4PWD) into Agent Bridge → Quick Setup in Foundry — it works even when the Agent is on your phone. (A full copy-paste code is also available for same-device setup.) Setup codes fetch your secret API key, so never share one with players.
  • Pairing QR (per player) — Once your Bridge is online, open Agent Bridge → Manage Characters and hit the QR button next to a player. They open Settings → Join a Session, tap Scan to Link Foundry, and point their camera at the code. Their Agent picks up the Channel ID and Foundry URL, and their character is linked automatically.

No camera? A copyable link code appears under the scan button — paste that instead. Codes are one-time use and expire after 5 minutes. Camera access needs an https:// (or localhost) connection.

Prefer to do it by hand? The manual steps below still work as a fallback.

2. GM Setup

Pick Game Master when you register (or switch role in Settings → Account Control) to unlock the GM flow.

  1. As the Game Master, navigate to the Settings page.
  2. Enter your Foundry URL, generate an API Key, and save — your game session (and Channel ID) is created automatically.
  3. Use the Foundry Setup Code (above) to configure the Bridge in one step — or manually paste the Channel ID and API Key into Configure Settings -> Agent Bridge in Foundry.
  4. Share your session code with your players — or skip codes entirely and hand them pairing QRs from Agent Bridge → Manage Characters.

3. Player Setup

Players must link their accounts to the GM's session:

  1. Log in to this Agent app and navigate to Settings.
  2. Generate your own API Key and copy it. Enter this key into your Foundry account settings provided by the GM (as below).
  3. Paste the Channel ID provided by your GM into the Channel ID field and click Commit Sync.
  4. Within Foundry VTT, go to Configure Settings -> Agent Bridge and enter your individual API Key.

4. Character Assignment & Sync

  1. In Foundry VTT, the GM should open the Character Assignment menu (found in the Agent Bridge module).
  2. The GM assigns a playable character to each player who has linked their API key.
  3. Once assigned, the player's Agent Link (a long unique code) should appear in the menu. The players must be online for this to appear, so dont worry if it doesn't appear straight away.
  4. The player is now fully synced. Character data, stats, and rolls will flow between Foundry and the Agent interface in real-time.

Want the full walkthrough — self-hosting, sharing over Tailscale, the QR handshake internals and troubleshooting? Read the complete GUIDE.md.

Return