# 📦 Copyparty Setup Guide — Windows

> **Self-Hosted File Server with Tailscale, HTTPS & Auto-Start on Windows**

---

## 📋 Table of Contents

| # | Section |
|---|---------|
| 1 | [What is Copyparty?](#1-what-is-copyparty) |
| 2 | [Prerequisites](#2-prerequisites) |
| 3 | [File Structure](#3-file-structure) |
| 4 | [Configuration File](#4-configuration-file) |
| 5 | [Auto-Start on Boot](#5-auto-start-on-boot) |
| 6 | [Tailscale Integration](#6-tailscale-integration) |
| 7 | [HTTPS Setup](#7-https-setup-optional) |
| 8 | [Managing Copyparty](#8-managing-copyparty) |
| 9 | [Security Considerations](#9-security-considerations) |
| 10 | [Troubleshooting](#10-troubleshooting) |

---

## 1. 📦 What is Copyparty?

Copyparty is a lightweight, portable file server written in Python. It runs as a single file with no complex dependencies and provides a full-featured web interface for managing files remotely.

### ✨ Key Features

- Web-based file upload and download with drag-and-drop
- Built-in media player for audio and video streaming
- Multiple user accounts with granular permission control
- Resumable uploads and downloads
- Runs on Linux, Windows, macOS, and Android

🔗 **GitHub:** https://github.com/9001/copyparty

### 💡 What You Can Do With This Setup

| Use Case | Description |
|----------|-------------|
| 📁 File sharing | Share files of any size between devices instantly |
| 🎧 Media streaming | Stream music and video directly in the browser |
| 📱 Mobile access | Access and upload files from any phone on Wi-Fi or mobile data |
| 🔒 Private cloud | No third-party services — everything stays on your hardware |
| 🌍 Remote access | Access your files from anywhere via Tailscale |

### 💰 Cost

| Tool | Cost | Notes |
|------|------|-------|
| Copyparty | Free | Open-source, no limits |
| Tailscale | Free | Up to 3 users, 100 devices |
| **Total** | **$0** | |

---

## 2. ✅ Prerequisites

| Requirement | Notes |
|-------------|-------|
| Windows 10 or 11 | |
| Python 3.x | Download from [python.org](https://www.python.org/downloads/windows/) — check "Add to PATH" during install |
| `copyparty-sfx.py` or `copyparty.exe` | Download from [GitHub Releases](https://github.com/9001/copyparty/releases) |
| Tailscale | *(Optional)* For remote access — download from [tailscale.com/download](https://tailscale.com/download) |
| NSSM | *(Optional)* For running as a Windows service — download from [nssm.cc](https://nssm.cc/download) |
| FFmpeg | *(Optional)* For thumbnails and media indexing — download from [gyan.dev](https://www.gyan.dev/ffmpeg/builds/) |

> 💡 **copyparty.exe vs copyparty-sfx.py:** The `.exe` is easier — no Python needed, just download and run. The `.py` file is smaller and considered safer but requires Python installed. Either works fine.

> 🎬 **FFmpeg** *(optional)*: Place `ffmpeg.exe` and `ffprobe.exe` in `C:\Windows\System32\` to enable thumbnails, audio transcoding, and music metadata search.

---

## 3. 📁 File Structure

Keep all copyparty files in one dedicated folder:

```
C:\Users\username\Copyparty\
├── copyparty-sfx.py        # Main copyparty script (or copyparty.exe)
├── copyparty.conf          # Configuration file
├── copyparty.pem           # TLS certificate  [optional]
├── renew-cert.ps1          # Certificate renewal script  [optional]
├── Browse\                 # Public read-only folder for guests
└── Dump\                   # Public upload folder for guests
```

**Create the guest folders in PowerShell:**

```powershell
New-Item -ItemType Directory -Path "$env:USERPROFILE\Copyparty\Browse" -Force
New-Item -ItemType Directory -Path "$env:USERPROFILE\Copyparty\Dump" -Force
```

---

## 4. ⚙️ Configuration File

📄 **Location:** `C:\Users\username\Copyparty\copyparty.conf`

The config file is identical across platforms — same syntax as Linux.

### 4.1 Complete Config

```ini
[global]
  i: 0.0.0.0
  p: 3923
  cert: C:\Users\username\Copyparty\copyparty.pem  # optional — remove if not using HTTPS

[accounts]
  alice: StrongPassphraseHere

[/]
  C:\Users\username
  accs:
    rwmda: alice

[/browse]
  C:\Users\username\Copyparty\Browse
  accs:
    r: *
    rwmda: alice

[/dump]
  C:\Users\username\Copyparty\Dump
  accs:
    wG: *
    rwmda: alice
  flags:
    e2d
    fk: 4
```

---

### 4.2 `[global]` — Server Settings

```ini
[global]
  i: 0.0.0.0
  p: 3923
  cert: C:\Users\username\Copyparty\copyparty.pem
```

| Option | Description |
|--------|-------------|
| `i: 0.0.0.0` | Bind to **all** network interfaces (LAN, Tailscale, localhost) at once |
| `p: 3923` | Port to listen on — 3923 is copyparty's default |
| `cert:` | *(Optional)* Path to TLS certificate PEM file for HTTPS |

> 💡 Using `0.0.0.0` means copyparty is automatically available on every interface, including Tailscale, without listing IPs individually.

---

### 4.3 `[accounts]` — User Accounts

```ini
[accounts]
  alice: StrongPassphraseHere
```

Creates user accounts in `username: password` format. Add multiple accounts one per line.

> 🔒 **Security:** Use a strong passphrase with mixed characters, numbers, and symbols. This is the primary protection for your private folders.

---

### 4.4 Volumes (Folders)

Each **volume** maps a URL path to a folder on disk and defines who can access it.

**General format:**

```ini
[/url-path]
  C:\absolute\path\to\folder
  accs:
    permissions: username
```

#### 🔑 Permission Reference

| Flag | Permission |
|------|------------|
| `r` | **Read** — browse and download files |
| `w` | **Write** — upload files |
| `m` | **Move** — rename and move files |
| `d` | **Delete** — delete files |
| `a` | **Admin** — access the admin panel |
| `G` | **upGet** — see only your own uploads (combine with `w` → `wG`) |
| `*` | **Wildcard** — applies to all unauthenticated guests |

Permissions can be combined freely, e.g. `rwmda` = full access, `wG` = upload + see own files only.

---

#### 📁 Volume: Private Root `/`

```ini
[/]
  C:\Users\username
  accs:
    rwmda: alice
```

Serves the user's home folder with full access. Guests cannot see this volume at all.

> **Alternative approach:** For better security, serve specific folders individually:
>
> ```ini
> [/documents]
>   C:\Users\username\Documents
>   accs:
>     rwmda: alice
>
> [/videos]
>   C:\Users\username\Videos
>   accs:
>     rwmda: alice
> ```

---

#### 📂 Volume: Browse `/browse`

```ini
[/browse]
  C:\Users\username\Copyparty\Browse
  accs:
    r: *
    rwmda: alice
```

A **public read-only** folder. Anyone can browse and download — only the admin can upload, move, or delete. Use this to share files publicly.

> 🎧 **Streaming:** Copyparty has a built-in media player. Audio and video files in any shared volume can be streamed directly in the browser — no download required.

---

#### 📤 Volume: Dump `/dump`

```ini
[/dump]
  C:\Users\username\Copyparty\Dump
  accs:
    wG: *
    rwmda: alice
  flags:
    e2d
    fk: 4
```

A **public upload** folder. Guests can upload and access only their own files via a unique filekey link.

| Flag | Description |
|------|-------------|
| `e2d` | Enables the uploads database — **required** for `wG` to work |
| `fk: 4` | Enables filekeys (4 chars). Each upload gets a unique `?k=XXXX` access key |

> 📎 **How filekeys work:** After uploading, the guest receives a unique link such as `/dump/filename.jpg?k=8TLN`. This is the **only** way to access the file later — the guest must save this link before navigating away.

---

### 4.5 Testing the Config

Before setting up auto-start, always test manually first. Open PowerShell and run:

```powershell
# If using copyparty-sfx.py
python "$env:USERPROFILE\Copyparty\copyparty-sfx.py" -c "$env:USERPROFILE\Copyparty\copyparty.conf"

# If using copyparty.exe
& "$env:USERPROFILE\Copyparty\copyparty.exe" -c "$env:USERPROFILE\Copyparty\copyparty.conf"
```

If it starts cleanly, open `http://localhost:3923` in your browser to verify. Press `Ctrl+C` to stop.

---

## 5. 🚀 Auto-Start on Boot

There are two methods to start copyparty automatically when Windows boots. Both are covered below with their pros and cons.

---

### Method A — Task Scheduler *(Built-in, no extra software)*

| | |
|--|--|
| ✅ Pros | Built into Windows, no extra downloads, easy to set up via GUI |
| ❌ Cons | Requires a user to be logged in, doesn't integrate with Windows Service Manager, limited restart-on-crash support |

**Setup via PowerShell (run as Administrator):**

```powershell
$action = New-ScheduledTaskAction `
  -Execute "python.exe" `
  -Argument "$env:USERPROFILE\Copyparty\copyparty-sfx.py -c $env:USERPROFILE\Copyparty\copyparty.conf" `
  -WorkingDirectory "$env:USERPROFILE\Copyparty"

$trigger = New-ScheduledTaskTrigger -AtLogOn

$settings = New-ScheduledTaskSettingsSet `
  -ExecutionTimeLimit 0 `
  -RestartCount 3 `
  -RestartInterval (New-TimeSpan -Minutes 1)

Register-ScheduledTask `
  -TaskName "Copyparty" `
  -Action $action `
  -Trigger $trigger `
  -Settings $settings `
  -RunLevel Highest `
  -Force
```

> ⚠️ Task Scheduler starts copyparty **after you log in**, not at boot. If you need it running before login, use Method B.

**Managing the task:**

```powershell
Start-ScheduledTask -TaskName "Copyparty"     # start
Stop-ScheduledTask -TaskName "Copyparty"      # stop
Unregister-ScheduledTask -TaskName "Copyparty" -Confirm:$false  # remove
```

---

### Method B — NSSM *(Recommended for always-on servers)*

| | |
|--|--|
| ✅ Pros | Runs before login, integrates with Windows Service Manager, auto-restart on crash, proper service behavior |
| ❌ Cons | Requires downloading NSSM separately, slightly more setup |

**Download NSSM:** https://nssm.cc/download — extract and place `nssm.exe` somewhere in your PATH (e.g. `C:\Windows\System32\`).

**Install copyparty as a service (run PowerShell as Administrator):**

```powershell
# If using copyparty-sfx.py
nssm install copyparty python.exe
nssm set copyparty AppParameters "$env:USERPROFILE\Copyparty\copyparty-sfx.py -c $env:USERPROFILE\Copyparty\copyparty.conf"

# If using copyparty.exe
nssm install copyparty "$env:USERPROFILE\Copyparty\copyparty.exe"
nssm set copyparty AppParameters "-c $env:USERPROFILE\Copyparty\copyparty.conf"

# Set working directory
nssm set copyparty AppDirectory "$env:USERPROFILE\Copyparty"

# Run as your own user account (important for correct file permissions)
nssm set copyparty ObjectName ".\yourusername" "yourWindowsPassword"

# Configure logging
nssm set copyparty AppStdout "$env:USERPROFILE\Copyparty\copyparty.log"
nssm set copyparty AppStderr "$env:USERPROFILE\Copyparty\copyparty-error.log"
nssm set copyparty AppRotateFiles 1

# Set restart on failure
nssm set copyparty AppExit Default Restart
nssm set copyparty AppRestartDelay 5000

# Start the service
nssm start copyparty
```

> ⚠️ Replace `yourusername` and `yourWindowsPassword` with your actual Windows credentials. This ensures copyparty runs with the right permissions to access your files.

**Managing the service:**

```powershell
nssm start copyparty      # start
nssm stop copyparty       # stop
nssm restart copyparty    # restart
nssm remove copyparty     # uninstall the service
nssm edit copyparty       # open GUI editor for the service
```

Or use the standard Windows Services panel: press `Win + R` → type `services.msc` → find **copyparty**.

---

### Method Comparison

| Feature | Task Scheduler | NSSM |
|---------|---------------|------|
| Extra software needed | ❌ No | ✅ Yes (nssm.exe) |
| Starts before login | ❌ No | ✅ Yes |
| Auto-restart on crash | Limited | ✅ Yes |
| Windows Service Manager integration | ❌ No | ✅ Yes |
| Complexity | Low | Medium |
| **Best for** | Casual personal use | Always-on home server |

---

## 6. 🔒 Tailscale Integration

Tailscale is a VPN built on WireGuard that creates a private encrypted network between your devices. Since copyparty binds to `0.0.0.0`, it is **automatically available** on your Tailscale IP — no extra configuration needed in copyparty.

> 🌐 **Cross-platform:** Tailscale is available on Linux, Windows, macOS, Android, and iOS. Anyone on your Tailscale network can access copyparty from any of these platforms using just a browser.

### 🌐 Access URL Reference

| Scenario | URL | Encryption |
|----------|-----|------------|
| Home network (LAN) | `http://192.168.1.x:3923` | None (trusted network) |
| Away from home, Tailscale on | `http://100.x.x.x:3923` | ✅ WireGuard |
| Via Tailscale domain | `https://hostname.tailnet.ts.net:3923` | ✅ WireGuard + TLS |
| Friend without Tailscale | `https://hostname.tailnet.ts.net` | ✅ TLS via Funnel |

> 💡 Traffic over the Tailscale IP is already encrypted end-to-end by WireGuard, even over plain HTTP. HTTPS over Tailscale is double-encrypted — useful but not strictly required.

---

### 6.1 MagicDNS

> ⚠️ **Required** if using the Tailscale domain or HTTPS certificates.

MagicDNS automatically assigns human-readable hostnames to all devices on your Tailscale network. It is what makes your Tailscale domain (`hostname.tailnet.ts.net`) resolve correctly — and it is automatically enabled when you turn on HTTPS certificates.

**To enable manually:** Go to https://login.tailscale.com/admin/dns and toggle on **MagicDNS**.

Once enabled, any device on your Tailscale network can reach copyparty using just the short hostname:

```
http://hostname:3923
```

---

### 6.2 Tailscale Funnel *(Optional)*

Funnel exposes copyparty to the **public internet** through Tailscale's servers. Anyone with the URL can access it — no Tailscale install required on their end.

**Requirements:**
- Tailscale account (only you need one — your friend needs nothing)
- HTTPS must be configured (Funnel requires it — see Section 7)

```powershell
# Step 1: Enable Funnel for your node
# Visit: https://login.tailscale.com/f/funnel?node=YOUR_NODE_ID

# Step 2: Start Funnel in the background
tailscale funnel --bg 3923

# Step 3: Verify
tailscale funnel status

# To disable
tailscale funnel --https=443 off
```

Funnel config **persists across reboots** automatically.

> 🐢 **Speed note:** Funnel routes traffic through Tailscale's relay servers, so speed depends on your home upload bandwidth. For fast transfers, add trusted contacts to your Tailscale network directly.

---

### 6.3 Adding Trusted Users to Tailscale *(Optional)*

1. Go to https://login.tailscale.com/admin/users
2. Click **Invite users** and send the invite link
3. They install Tailscale and accept the invite
4. They access copyparty at `http://100.x.x.x:3923` or `http://hostname:3923`

> ⚠️ Adding someone to your Tailscale network gives them access to your **entire** private network. Only invite people you trust.

---

## 7. 🔐 HTTPS Setup *(Optional)*

### ✅ Option A — Tailscale Certificate (Recommended)

```powershell
# Step 1: Enable HTTPS Certificates in Tailscale admin
# https://login.tailscale.com/admin/dns → Enable HTTPS Certificates

# Step 2: Generate the certificate
tailscale cert hostname.tailnet.ts.net

# Step 3: Combine cert + key into a single PEM file
Get-Content hostname.tailnet.ts.net.crt, hostname.tailnet.ts.net.key `
  | Set-Content "$env:USERPROFILE\Copyparty\copyparty.pem"

# Step 4: Add to copyparty.conf [global] section:
#   cert: C:\Users\username\Copyparty\copyparty.pem

# Step 5: Restart copyparty (Task Scheduler)
Stop-ScheduledTask -TaskName "Copyparty"
Start-ScheduledTask -TaskName "Copyparty"

# Or restart via NSSM
nssm restart copyparty
```

> ⏳ **Tailscale certificates expire every 90 days.** Use the renewal script below.

**Renewal Script** — save as `C:\Users\username\Copyparty\renew-cert.ps1`:

```powershell
tailscale cert hostname.tailnet.ts.net
Get-Content hostname.tailnet.ts.net.crt, hostname.tailnet.ts.net.key `
  | Set-Content "$env:USERPROFILE\Copyparty\copyparty.pem"
nssm restart copyparty   # or use Stop/Start-ScheduledTask if using Task Scheduler
Write-Host "Certificate renewed and copyparty restarted!"
```

```powershell
# Run when cert expires (~every 90 days)
& "$env:USERPROFILE\Copyparty\renew-cert.ps1"
```

---

### Option B — Self-Signed Certificate via cfssl *(Optional)*

Copyparty auto-generates a self-signed certificate if `cfssl` is installed.

```powershell
# Download from: https://github.com/cloudflare/cfssl/releases/latest
# Place cfssl.exe, cfssljson.exe, cfssl-certinfo.exe in C:\Windows\System32\

# Copyparty auto-generates certs on next start
nssm restart copyparty
```

> ⚠️ Self-signed certs trigger browser security warnings on every device. You must manually install the generated `ca.pem` on each device to suppress them. Option A is generally preferable.

---

## 8. 🛠️ Managing Copyparty

### ▶️ Start / Stop / Restart

**If using Task Scheduler:**
```powershell
Start-ScheduledTask -TaskName "Copyparty"
Stop-ScheduledTask -TaskName "Copyparty"
```

**If using NSSM:**
```powershell
nssm start copyparty
nssm stop copyparty
nssm restart copyparty
```

**Or via Windows Services panel:**
Press `Win + R` → type `services.msc` → find **copyparty** → right-click to Start/Stop/Restart.

---

### 📋 Viewing Logs

**If using NSSM** (logs configured during setup):
```powershell
# View live log
Get-Content "$env:USERPROFILE\Copyparty\copyparty.log" -Wait

# View last 50 lines
Get-Content "$env:USERPROFILE\Copyparty\copyparty.log" -Tail 50
```

**If running manually:**
Output appears directly in the PowerShell window.

---

### 🧪 Testing Config Manually

Always test config changes manually before restarting the service:

```powershell
python "$env:USERPROFILE\Copyparty\copyparty-sfx.py" -c "$env:USERPROFILE\Copyparty\copyparty.conf"
```

If it starts cleanly, press `Ctrl+C` and restart the service.

---

## 9. 🛡️ Security Considerations

### Strengths of This Setup
- Strong passphrase protects all private volumes
- Guests are sandboxed to `/browse` (read-only) and `/dump` (upload + own files only)
- Funnel only exposes guest-accessible volumes to the public internet
- HTTPS encrypts traffic on the Tailscale domain
- WireGuard encrypts all Tailscale IP traffic end-to-end

### ⚠️ Known Risks

| Risk | Severity | Mitigation |
|------|----------|------------|
| Copyparty runs as your main user account | Medium | Create a dedicated Windows user account for the service (advanced) |
| LAN traffic is plain HTTP | Low | Trusted home network; acceptable for personal use |
| Home folder served at root volume | Medium | Use a strong unique passphrase; or serve specific subfolders instead |
| Self-signed cert causes browser warnings | Low | Use Tailscale cert (Option A) instead |
| Config file contains plaintext password | Low | Restrict file permissions — see below |

### 🔐 Protecting the Config File

```powershell
# Remove all permissions and grant only your account access
$acl = Get-Acl "$env:USERPROFILE\Copyparty\copyparty.conf"
$acl.SetAccessRuleProtection($true, $false)
$rule = New-Object System.Security.AccessControl.FileSystemAccessRule(
  $env:USERNAME, "FullControl", "Allow"
)
$acl.SetAccessRule($rule)
Set-Acl "$env:USERPROFILE\Copyparty\copyparty.conf" $acl
```

### 🔐 Password Best Practices
- Use a passphrase of 3+ random words combined with numbers and special characters
- Never reuse this password from another service
- Change it immediately if you suspect it was compromised

---

## 10. 🔧 Troubleshooting

#### ❌ Copyparty won't start
Check the log file for errors:
```powershell
Get-Content "$env:USERPROFILE\Copyparty\copyparty-error.log" -Tail 50
```
Or run manually in PowerShell to see output directly.

---

#### 🔥 Windows Firewall blocking access
Allow copyparty through the firewall:
```powershell
New-NetFirewallRule `
  -DisplayName "Copyparty" `
  -Direction Inbound `
  -Protocol TCP `
  -LocalPort 3923 `
  -Action Allow
```

---

#### 🔒 HTTPS certificate errors
The Tailscale cert may have expired. Renew it:
```powershell
& "$env:USERPROFILE\Copyparty\renew-cert.ps1"
```

---

#### 📡 Can't access via Tailscale IP
Verify Tailscale is connected:
```powershell
tailscale status
tailscale ip -4
```
Restart copyparty after Tailscale reconnects.

---

#### 🌍 Funnel not working
```powershell
tailscale funnel status
tailscale funnel --bg 3923
```

---

#### 📎 Guest can't find their upload
The filekey link (`?k=XXXX`) shown after uploading is the **only** way back to the file. It must be saved before navigating away.

---

#### ⚙️ Config changes not taking effect
Restart copyparty after every config change:
```powershell
nssm restart copyparty
# or
Stop-ScheduledTask -TaskName "Copyparty"; Start-ScheduledTask -TaskName "Copyparty"
```

---

*Guide covers Copyparty v1.20.x on Windows 10/11. Commands use PowerShell.*