Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
Deploy Piik Server
English · 简体中文 · Documentation
Piik Server packages the web interface, room management and optional media forwarding in one server binary. Extract and run it; room data is stored in SQLite.
The default P2P configuration handles room management, signaling and STUN; shared video and audio travel between participants. Enabling SFU adds media-forwarding bandwidth and processing on the server. For a small server, start with the default and measure CPU, memory and network use with your intended number of rooms and viewers before enabling SFU. Lowering picture resolution primarily reduces participants' capture and encoding work.
Try it locally
Server packages are available for Linux x64/ARM64 and Windows x64.
Download the Server archive matching your machine
from GitHub Releases
or the AtomGit mirror.
On Linux, use uname -m to check the architecture:
| Platform | Archive |
|---|---|
Linux x86_64 (x64) |
piik-<revision>-runtime.tar.gz |
Linux aarch64 (ARM64) |
piik-<revision>-linux-arm64-runtime.tar.gz |
| Windows x64 | piik-<revision>-windows-amd64-runtime.zip |
Extract it and run the following in its directory on Linux:
./piik-server
On Windows, open PowerShell in the extracted directory and run ./piik-server.exe.
Open http://localhost:8787. This is a local trial; use the configuration below
to let friends connect over the internet. To start a temporary room on your computer,
use the Piik App guide.
Docker Compose
On a Linux x64 or ARM64 server with Docker Compose v2, download the two deployment files into an empty directory:
curl -fsSLo compose.yaml https://raw.githubusercontent.com/TNTcraftHIM/Piik/main/deploy/container/compose.yaml
curl -fsSLo .env https://raw.githubusercontent.com/TNTcraftHIM/Piik/main/deploy/container/.env.example
Replace share.example.com in .env with your domain, then start Piik:
docker compose run --rm piik --check-config
docker compose up -d
The ghcr.io/tntcrafthim/piik:latest image includes the Web UI, signaling, STUN
and optional SFU. Docker selects the matching architecture automatically. Complete HTTPS and
firewall configuration below. The default is P2P;
the sample .env also shows how to enable SFU fallback. Keep the piik-data
volume, which stores room data and optional diagnostics. See
container maintenance for updates and backups.
Private LAN without a domain
For a NAS, home server or virtual LAN, Piik can serve HTTPS directly. Save the
following as .env beside the server binary, replacing every 192.168.1.10
with the server's address on that network:
PIIK_ENV=production
LISTEN_HOST=0.0.0.0
PORT=8787
PUBLIC_BASE_URL=https://192.168.1.10:8787
TLS_SELF_SIGNED=true
STUN_URLS=stun:192.168.1.10:3478
From that directory, run ./piik-server --check-config, then ./piik-server
(use .exe on Windows).
Allow TCP 8787 and UDP 3478 on that network. Open the HTTPS address on each
device; no public IP, domain or reverse proxy is needed. With Docker Compose,
also change the web port mapping from 127.0.0.1:8787:8787/tcp to
8787:8787/tcp so LAN devices can reach it.
The browser will warn about the self-signed certificate. Compare its SHA-256 fingerprint with the server's HTTPS certificate startup message before continuing; see local certificate confirmation. The certificate stays in memory and changes when Piik restarts, so confirm the new one after a restart. Browser microphone, camera and remote control still require their ordinary permissions and supported APIs.
To keep your own certificate, turn off TLS_SELF_SIGNED and set both
TLS_CERT_FILE and TLS_KEY_FILE to its PEM files. With Docker, mount those
files read-only and use their paths inside the container. The certificate must cover
the host in PUBLIC_BASE_URL. --check-config checks the pair and validity;
restart Piik after replacing the files. Piik does not obtain or renew these
certificates. For a long-running public site, use the automatic HTTPS proxy below.
If the web port is occupied, stop the conflicting service or change both PORT
and the port in PUBLIC_BASE_URL, then send new invitations.
Put it online
You need a supported server and a domain pointing to its public IP.
The example uses share.example.com; replace it with your domain.
1. Configure and start Piik
Create a .env file next to the binary:
PIIK_ENV=production
LISTEN_HOST=127.0.0.1
PUBLIC_BASE_URL=https://share.example.com
STUN_URLS=stun:share.example.com:3478
MAX_VIEWERS_PER_ROOM=20
SITE_ACCESS_PASSWORD=
Run these commands from that directory as a regular user:
./piik-server --check-config
./piik-server
On Windows, use ./piik-server.exe --check-config and ./piik-server.exe in
PowerShell. The same .env file and ports apply.
The server reads .env automatically and stores rooms in rooms.sqlite in the
working directory. A blank SITE_ACCESS_PASSWORD allows
entry without a site passphrase; enter a passphrase to require one.
Room invitations and access settings still apply.
PUBLIC_BASE_URL must match the address opened in the browser, including HTTPS
and any non-default port. Leave ALLOWED_ORIGINS unset or empty for this single
address. An existing non-empty value overrides that default; a stale value can
cause 403 when creating a room.
MAX_VIEWERS_PER_ROOM sets the room's Viewer limit, excluding the Host. Choose
1..20 and restart to apply it. More Viewers can require more network and relay
resources. See room capacity
for defaults and the difference from App rooms.
For a public site, optionally set ROOM_EMPTY_TIMEOUT_SECONDS=3600 and restart.
Rooms with nobody connected are reclaimed after an hour; if all room codes are
used, the oldest empty room can be reclaimed earlier. Occupied rooms keep working.
Reclaimed rooms need new invitations. Unset or 0 keeps the default indefinite
retention; see room retention.
2. Enable HTTPS
Use your existing HTTPS reverse proxy to forward to 127.0.0.1:8787 with
WebSocket support. If you do not have one, install Caddy
and add this to its Caddyfile:
share.example.com {
reverse_proxy 127.0.0.1:8787
}
Reload Caddy. It obtains and renews the certificate automatically when DNS points to the server and TCP 80/443 are reachable. See Caddy's HTTPS proxy guide.
For nginx, see the configuration example.
If you copied an older example, change its Permissions-Policy to
camera=(self), microphone=(self), geolocation=() and reload nginx. Empty
camera/microphone allowlists prevent Browser capture even when the user grants
permission; self allows this site to request access.
3. Open the ports and verify
Allow TCP 80/443 for HTTPS and UDP 3478 for STUN in the server firewall
and cloud security group. Keep TCP 8787 private. The STUN hostname must resolve
directly to the server; a CDN HTTP proxy does not forward its UDP traffic.
See the complete port table
for optional services. Embedded SFU media shares the single UDP port set by
SFU_UDP_PORT.
Open https://share.example.com/healthz; it should return {"status":"ok"}.
Then open the site, share a screen and join from another device. This initial
configuration uses P2P media, so participants need a usable UDP path.
Optional: media fallback
Add SFU_UDP_PORT=7882 to .env, allow UDP 7882, and restart Piik to enable
automatic SFU fallback. When the server is behind NAT, also set SFU_PUBLIC_IP
to its reachable public IPv4 address or DDNS hostname and forward the same external
and internal UDP port as SFU_UDP_PORT. Use a hostname pointing directly to that
IPv4, with the CDN proxy disabled. Piik resolves it at startup and every minute.
After DDNS updates, new media connections use the updated address without a
service restart. If the address change interrupted an ongoing share, the Host
can restart sharing and Viewers can rejoin the room.
The same binary provides the fallback.
Allow server forwarding capacity and outbound bandwidth for Viewers actually
using the SFU.
The Host must turn off Privacy mode before sharing to allow this route.
Both direct and SFU media need a usable UDP connection.
To send every room through your server, also set SFU_ONLY=true and restart.
The sharing settings will show Server media. Plan server bandwidth for every
Viewer; this mode does not fall back to P2P if the server route fails.
Optional: forward an existing server with frp
If Piik runs behind NAT and you control a public frps host, frp can forward its existing web and SFU endpoints. P2P ICE discovery remains unchanged.
Run the HTTPS proxy above on the public host, keeping its
WebSocket-capable upstream at 127.0.0.1:8787. Point share.example.com and
relay.example.com to that host. Open TCP 7000 for frpc and UDP 7882 for media,
alongside TCP 80/443; keep the forwarded TCP 8787 private to the HTTPS proxy.
On the public host, configure frps.toml:
bindPort = 7000
auth.token = "{{ .Envs.FRP_TOKEN }}"
transport.tls.force = true
allowPorts = [{ single = 8787 }, { single = 7882 }]
On the Piik machine, copy frpc.toml.example
to frpc.toml and replace relay.example.com. Inject the same private, nonempty
FRP_TOKEN into both frp process environments. Validate each file with
frps verify -c frps.toml / frpc verify -c frpc.toml, then start each process
with -c and its file. See frp configuration
and TCP/UDP forwarding.
Keep Piik's LISTEN_HOST=127.0.0.1 and update its .env:
PUBLIC_BASE_URL=https://share.example.com
STUN_URLS=stun:stun.direct.example.com:3478
SFU_UDP_PORT=7882
SFU_PUBLIC_IP=203.0.113.10
Replace the example IPv4 with the public frps address and the STUN hostname with
a directly reachable STUN service. The frpc local and remote UDP ports must both
equal SFU_UDP_PORT. Do not forward Piik's STUN ports through frp: its UDP proxy
changes the source mapping
STUN would report. Restart Piik and check HTTPS health, room access and
Server media from another network.
Using a managed frp provider
Services such as SakuraFrp supply the public server and their own client or launcher. Follow the provider's setup instead of copying the private frps token configuration above. Check that the chosen node supports both HTTPS web access with WebSockets and an ordinary UDP tunnel.
| Endpoint | Local target | Piik setting |
|---|---|---|
| Web | 127.0.0.1:8787, with HTTPS supplied by your proxy or provider |
Set PUBLIC_BASE_URL to the actual public HTTPS address, including any port. |
| Media | 127.0.0.1:<assigned UDP port> |
Set SFU_UDP_PORT to that same local/public port and SFU_PUBLIC_IP to the UDP node's public IPv4. |
For example, if the provider assigns UDP port 30000, use 30000 for both
tunnel ports and Piik's SFU_UDP_PORT; the web port can remain 8787 locally.
Keep STUN directly reachable as above. A web-only tunnel carries signaling but
does not add an SFU media route for strict NAT.
See SakuraFrp's web setup and UDP connectivity notes. Node features, access requirements and bandwidth depend on the provider; Piik has not yet field-tested this managed service.
Keep it running and update
On Linux, use the systemd or container guide for automatic
startup. On Windows, run the executable under your existing service manager or
Task Scheduler; Piik does not install a Windows service.
Keep .env and rooms.sqlite across updates. Back up room data while the server is
stopped, replace the executable with the new release, then restart and check
health and room access. Read release notes before an upgrade that changes data formats.