INSTALL

Install junto

junto runs on macOS and Linux. Pick your platform below, then verify with junto doctor. Windows support is on the roadmap.

macOS with Homebrew

The Homebrew tap installs junto and mpv in one step, so you have everything the room needs.

brew install swayam-mishra/tap/junto

Don’t have Homebrew? Install it from brew.sh first. Already installed junto? brew upgrade junto updates it.

Linux release binary

Grab the binary for your architecture from GitHub Releases, put it on your PATH, and install mpv from your package manager.

  1. 1 · Download the tarball for your arch

    curl -L -o junto.tar.gz https://github.com/swayam-mishra/junto/releases/latest/download/junto_linux_amd64.tar.gz

    On ARM machines (e.g. a Raspberry Pi or arm64 server) use junto_linux_arm64.tar.gz. Browse every build on GitHub Releases.

  2. 2 · Extract and install onto your PATH

    tar -xzf junto.tar.gz && sudo install junto /usr/local/bin/junto

  3. 3 · Install mpv from your package manager

    sudo apt install mpv # Debian/Ubuntu
    sudo dnf install mpv # Fedora
    sudo pacman -S mpv # Arch

From source with go install

With Go 1.23+ you can build junto straight from source. You still need mpv installed separately.

go install github.com/swayam-mishra/junto/cmd/junto@latest

This drops the junto binary in $(go env GOPATH)/bin, so make sure that’s on your PATH. Source and build instructions live on GitHub.

Verify your install

Confirm the binary works, then let junto doctor preflight-check mpv, relays, NAT, and disk space before you host or join.

Check the version

Run the preflight

Configure (optional)

To avoid retyping flags, drop defaults in ~/.config/junto/config.toml (or $XDG_CONFIG_HOME). Explicit flags on the command line still override the file.

~/.config/junto/config.toml

nick = "alice"
relays = ["wss://relay.damus.io", "wss://nos.lol"]
mpv-path = "/usr/local/bin/mpv"
# turn = "turn:relay.example:3478"
# turn-user = "user"
# turn-pass = "pass"

junto persists nick, relays, mpv-path, and your turn credentials, so you set them once and forget them.

Watch from a URL (optional)

Hand junto create an http(s) link and junto fetches the video with yt-dlp, then hosts it like any local file. You supply the link; junto provides no content of its own.

junto create "https://youtu.be/aqz-KE-bpKQ"

URL sources need yt-dlp and ffmpeg on your PATH (junto doctor checks for both). Downloads are capped at 1080p by default (override with -quality best) and cached in ~/.cache/junto, so a second watch is instant. Mix files and links freely: junto create intro.mkv "https://youtu.be/…". Live streams aren’t supported yet.

Update & uninstall

Both commands respect how you installed junto, so you never fight your package manager.

Update to the latest release

junto update

A standalone binary updates itself in place (checksum-verified). Installed via Homebrew? junto points you to brew upgrade swayam-mishra/tap/junto. A go install build points back to go install.

Remove junto

junto uninstall

Removes a standalone binary; add -purge to also clear ~/.config/junto and ~/.cache/junto. Homebrew installs delegate to brew uninstall junto. mpv, yt-dlp, and ffmpeg are left alone.

Troubleshooting

These mirror the checks junto doctor runs. If a check fails, here’s the fix.

“mpv not found on PATH”
junto drives mpv and can’t run without it. On macOS the Homebrew formula installs mpv for you; on Linux install it from your package manager (apt, dnf, pacman). Re-run junto doctor to confirm.
“relays unreachable”
junto coordinates over free public nostr relays. If none are reachable, check your internet connection and any firewall blocking outbound WebSocket traffic. Relays carry only encrypted coordination, never your file.
“NAT: symmetric (direct connections may fail)”
Strict or symmetric NATs can block direct peer-to-peer connections. Supply your own TURN relay with the -turn flag, since junto has no built-in relay. If that isn’t an option, share the file another way and use junto to keep playback in sync.
“not enough free disk space”
Joiners download the file as they stream it, so each needs room for the whole media file in the working directory. Free up space or point junto at a larger volume, then try again.

Still stuck? Open an issue on GitHub and include the output of junto doctor.