GUIDE How to send torrents directly to your docker-transmission-openvpn instance in windows

[new112211]

I’m running docker-transmission-openvpn inside a docker instance on a NAS. This script allows me to do the following:

Click magnet link → torrent appears on server instantly
Whenever I click on a MAGNET URL anywhere on my PC or on any website, the URL magnet torrent is captured and sent automatically to my client running on my NAS. No popups, browser tabs, or manual copying and pasting.

I created this because a useful browser extension, that I previously used to automatically add torrents to my client when clicking on magnet links, had stopped working. (google’s fault not the dev’s). After this, I became tired of copying and pasting the links or having to keep my client open/running on my PC just for it to remotely add magnets.

This is a direct magnet to transmission RPC integration, that allows you to set windows to use your remote transmission client, that’s running on your NAS, as the default URL protocol handler for windows.
Meaning, when you click on a magnet link, windows automatically sends and adds it to your remote transmission client. Done, simple effective and fast! No browser extensions, no switching between tabs, no local torrent clients running on your PC, or browser JavaScript hacks, needed.

What This Does
This system creates a custom Windows protocol handler for magnet URLs. The magnet link gets sent directly to Transmission RPC API.

Supports:

• Sound Notifications: success, duplicate & error sound feedback
• Logging & Debugging
  • timestamped logging
  • automatic log cleanup (after 30 days)
  • RPC error logging
  • duplicate detection

WORK FLOW
Magnet Link Clicked
↓
Windows Protocol Handler
↓
VBScript Launcher
↓
PowerShell RPC Script
↓
Transmission RPC API
↓
Torrent Added To Client

Installation Guide/Requirements
Tested on windows 10
Transmission RPC Enabled needs to be enabled, if not already.

• have RPC enabled
• expose RPC port
• allow authentication (if you don’t want to use the authentication, you’ll have to change the ps1 script)

Example docker environment variables:

• TRANSMISSION_RPC_ENABLED=true
• TRANSMISSION_RPC_PORT=9091

INSTALLATION GUIDE
Its super simple and quick, this guide just makes it look longer as I tried to put as much information as I could.

1. Remove current Magnet Associations
   If you currently have a program already associated with magnet links, to register with windows this new script, you’ll have to clear the ones you set. You can check this in

• Settings → Apps → Default apps → Choose default applications by protocol → Magnet
  If its blank, you can skip this step, otherwise delete the following keys in the registry:

- HKEY_CLASSES_ROOT\magnet
- HKEY_CURRENT_USER\Software\Classes\magnet
- HKEY_LOCAL_MACHINE\Software\Classes\magnet
- HKEY_CURRENT_USER\Software\Microsoft\Windows\Shell\Associations\UrlAssociations\magnet

2. Create Folder Structure on your PC _(if you use your own locations, don’t forget to update the files to reflect change)
   a. Create: C:\Scripts\protocol-handler-URL-magnet\

3. Create PowerShell Script
   a. Create: C:\Scripts\protocol-handler-URL-magnet\add-magnet.ps1
   This script:

• authenticates with Transmission
• negotiates session IDs
• submits magnet links
• plays sounds
• logs events
  b. be sure to change the following
  i. the USERNAME & PASSWORD

- $username = "YOUR-USERNAME"
- $password = "YOUR-PASSWORD"

ii. Your remote IP & port XXXX to access your docker transmission
- $rpcUrl = "http://XXX.X.X.X:XXXX/transmission/rpc/"
The “rpc/” is required in your url as detailed in the documentation for “VPN and Networking” in this repository wiki (I was stuck on this for a while)
https://haugene.github.io/docker-transmission-openvpn/vpn-networking/

4. Create VBScript Launcher
   a. Create: C:\Scripts\protocol-handler-URL-magnet\magnet-launcher.vbs

5. Create Registry file
   a. Create: C:\Scripts\protocol-handler-URL-magnet\register-magnet-launcher.reg
   This does:

• registers the magnet: protocol
• associates it with the launcher
• allows Windows Default Apps to use your custom file

6. Import Registry File
   Import register-magnet-launcher.reg into your registry to tell windows to use your custom script to handle magnet protocols

7. Reboot windows
   REQUIRED

If you’d like to check if the registry was updated correctly run
reg query "HKEY_CURRENT_USER\Software\Classes\magnet\shell\open\command" in cmd.
Result should show (Default) REG_SZ wscript.exe "C:\Scripts\protocol-handler-URL-magnet\magnet-launcher.vbs" "%1"

8. Set the protocol handler for magnet links. To do this either
   a. click on a magnet link and in the popup that asks “How do you want to open this file” select Either “Microsoft Windows Based Script Host” or the name of your custom launcher/script and enable the check box: "Always use this app”
   b. Or instead Manually set it in the settings, same as step 1, select Microsoft Windows Based Script Host

Done. Now next time you click a magnet link, it’ll be instantly (almost) added to your remote torrent client, with audible feedback notifications. Event logging enabled if required. Log will be saved to the same location

SECURITY NOTES
Do NOT expose Transmission RPC directly to the internet.
Recommended:
• restrict RPC access to LAN only

TESTING:
To check if your client PowerShell RPC script itself actually works, before putting it into production,
Run in powershell using a dummy test torrent
powershell.exe -NoProfile -ExecutionPolicy Bypass -File "C:\Scripts\protocol-handler-URL-magnet\add-magnet.ps1" "magnet:?xt=urn:btih:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
should return

- {"result":"success"} or 
- {"result":"duplicate torrent"} 

or similar, then it works
if it returns {"result":"unrecognized info"}, then there’s an issue with the RPC layer

Originally took inspiration from fatflyingpigs who posted a great solution to a kind-of similar issue, I just took it in a completely different direction
fatflyingpigs on Jan 17, 2023
qbittorrent/qBittorrent#12605 (comment)

Had some help from chatgbt
Also just wanted to say, its amazing the work people put in to create this amazing repository. Thank you! 😊
Also sorry if the guides not quite correct, it’s the first I’ve written but hopefully its been of some help.

The required files:

### magnet-launcher.vbs

Dim shell
Set shell = CreateObject("WScript.Shell")

Dim magnet
magnet = WScript.Arguments(0)

shell.Run "powershell.exe -NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File ""C:\Scripts\protocol-handler-URL-magnet\add-magnet.ps1"" """ & magnet & """", 0, False

register-magnet-launcher.reg

Windows Registry Editor Version 5.00

; =========================
; Register fake application
; =========================

[HKEY_CURRENT_USER\Software\Classes\MagnetLauncher]

@="Magnet Launcher"

[HKEY_CURRENT_USER\Software\Classes\MagnetLauncher\shell]

[HKEY_CURRENT_USER\Software\Classes\MagnetLauncher\shell\open]

[HKEY_CURRENT_USER\Software\Classes\MagnetLauncher\shell\open\command]
@="wscript.exe \"C:\\Scripts\\protocol-handler-URL-magnet\\magnet-launcher.vbs\" \"%1\""

; =========================
; Register protocol
; =========================

[HKEY_CURRENT_USER\Software\Classes\magnet]
@="URL:Magnet Protocol"
"URL Protocol"=""

[HKEY_CURRENT_USER\Software\Classes\magnet\DefaultIcon]
@="C:\\Windows\\System32\\shell32.dll,1"

[HKEY_CURRENT_USER\Software\Classes\magnet\shell]

[HKEY_CURRENT_USER\Software\Classes\magnet\shell\open]

[HKEY_CURRENT_USER\Software\Classes\magnet\shell\open\command]
@="wscript.exe \"C:\\Scripts\\protocol-handler-URL-magnet\\magnet-launcher.vbs\" \"%1\""

; =========================
; Register app capabilities
; =========================

[HKEY_CURRENT_USER\Software\RegisteredApplications]
"MagnetLauncher"="Software\\Clients\\StartMenuInternet\\MagnetLauncher\\Capabilities"

[HKEY_CURRENT_USER\Software\Clients\StartMenuInternet\MagnetLauncher]

@="Magnet Launcher"

[HKEY_CURRENT_USER\Software\Clients\StartMenuInternet\MagnetLauncher\Capabilities]
"ApplicationName"="Magnet Launcher"
"ApplicationDescription"="Custom magnet handler"

[HKEY_CURRENT_USER\Software\Clients\StartMenuInternet\MagnetLauncher\Capabilities\URLAssociations]
"magnet"="MagnetLauncher"

add-magnet.ps1

param(
    [Parameter(ValueFromRemainingArguments = $true)]
    [string[]]$MagnetArgs
)

$Magnet = $MagnetArgs -join ' '

# --- Logging ---
$LogFile = "C:\Scripts\protocol-handler-URL-magnet\magnet-log.txt"
$LogRetentionDays = 30

# --- Logging function ---
function Write-Log($message) {
    $timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
    Add-Content -Path $LogFile -Value "[$timestamp] $message"
}
# --- AUTO LOG CLEANUP ---
if (Test-Path $LogFile) {

    $age = (Get-Date) - (Get-Item $LogFile).LastWriteTime

    if ($age.Days -ge $LogRetentionDays) {

        Remove-Item $LogFile -Force

        Add-Content -Path $LogFile -Value "[$(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')] Log cleanup performed"

    }

}

# --- Log incoming magnet ---
Write-Log "Received magnet: $Magnet"


$rpcUrl = "http://XXX.XXX.XXX.XXX:XXXX/transmission/rpc/"

# --- AUTH ---
$username = "YOUR-USERNAME"
$password = "YOUR-PASSWORD"

$pair = "$username`:$password"
$base64 = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes($pair))

$headers = @{
    "Authorization" = "Basic $base64"
}

# --- SOUND HELPERS ---
function Play-Wav($path) {
    try {
        $player = New-Object System.Media.SoundPlayer
        $player.SoundLocation = $path
        $player.Load()
        $player.PlaySync()
    }
    catch {
    }
}

# Built-in Windows sounds
$SuccessSound = "C:\Windows\Media\Windows Exclamation.wav"
$DuplicateSound = "C:\Windows\Media\Windows Critical Stop.wav"
$ErrorSound = "C:\Windows\Media\chord.wav"

function Play-SuccessSound {
    Play-Wav $SuccessSound
}

function Play-DuplicateSound {
    Play-Wav $DuplicateSound
}

function Play-ErrorSound {
    Play-Wav $ErrorSound
}

# --- Prevent empty magnet execution ---
if ([string]::IsNullOrWhiteSpace($Magnet)) {

    Write-Log "ERROR: Empty magnet URI received"
    Play-ErrorSound
    exit 1

}

# --- STEP 1: GET SESSION ID ---
try {
    $response = Invoke-WebRequest `
        -Uri $rpcUrl `
        -Method Post `
        -Headers $headers `
        -Body "{}" `
        -UseBasicParsing `
	# use for PowerShell 7+ (pwsh) -TimeoutSec 15 `
        -ErrorAction Stop
}
catch {
    $response = $_.Exception.Response
}

$sessionId = $response.Headers["X-Transmission-Session-Id"]
# --- SessionID error log & sound ---
if (-not $sessionId) {
    Write-Log "ERROR: Failed to obtain Transmission session ID"
    Play-ErrorSound
    exit 1
}

# --- STEP 2: BUILD JSON PAYLOAD ---
$json = @{
    method = "torrent-add"
    arguments = @{
        filename = $Magnet
        paused = $false
    }
} | ConvertTo-Json -Depth 10

$utf8 = [System.Text.Encoding]::UTF8.GetBytes($json)

# --- STEP 3: SEND REQUEST ---
try {

    $result = Invoke-WebRequest `
        -Uri $rpcUrl `
        -Method Post `
        -Headers @{
            "Authorization" = "Basic $base64"
            "X-Transmission-Session-Id" = $sessionId
            "Content-Type" = "application/json"
        } `
        -Body $utf8 `
        -UseBasicParsing
	# use for PowerShell 7+ (pwsh) -TimeoutSec 15

    # --- SUCCESS / FAILURE DETECTION Sound & Log RPC ---

    $content = $result.Content | ConvertFrom-Json

    if ($content.result -ne "success") {

        Write-Log "ERROR: RPC failure: $($result.Content)"
        Play-ErrorSound

    }
    elseif ($content.arguments."torrent-duplicate") {

        $name = $content.arguments."torrent-duplicate".name

        Write-Log "DUPLICATE: $name"
        Play-DuplicateSound

    }
    elseif ($content.arguments."torrent-added") {

        $name = $content.arguments."torrent-added".name

        Write-Log "ADDED: $name"
        Play-SuccessSound

    }
    else {

        Write-Log "UNKNOWN RESPONSE: $($result.Content)"
        Play-SuccessSound

    }

}
catch {

    Write-Log "EXCEPTION: $($_.Exception.Message)"
    Play-ErrorSound

}