INSTALL

Install junto

junto runs on macOS and Linux. The fastest way in is one command; the by-hand options are right below. Either way, finish with junto doctor. Windows is still on the roadmap.

  • macOS
  • Linux
  • Windows soon

macOS and Linux, one command

The fastest way in. It works out your platform, grabs the right binary (checksum-verified, so nothing sneaky slips in), and installs mpv for you.

curl -fsSL https://junto.watch/install | sh

Piping a script straight into sh on trust? Smart to peek first. Read the exact script junto.watch serves (it's the same file that lives in the repo) before you run it.

Rather do it by hand, or want a double-click installer? Pick your platform below. Every option except Homebrew and this one-liner needs mpv installed separately.

macOS with Homebrew

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

brew install --cask swayam-mishra/tap/junto

Don’t have Homebrew? Install it from brew.sh first. Already installed junto? brew upgrade swayam-mishra/tap/junto updates it. Installed with the old brew install swayam-mishra/tap/junto command (no --cask)? Reinstall with the command above.

Not a terminal person? The double-click .pkg installer on the GitHub releases page installs junto and pulls in mpv for you.

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

    From the GitHub releases page, grab junto_<version>_linux_amd64.tar.gz into your working directory. On ARM machines (a Raspberry Pi or arm64 server) grab junto_<version>_linux_arm64.tar.gz instead.

  2. 2 · Extract and install onto your PATH

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

  3. 3 · Install mpv from your package manager

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

From source with go install

With Go 1.26+ 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 cask 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. junto handles this for you: when a direct connection can’t punch through, it quietly retries through a built-in relay with no configuration, so most stubborn routers sort themselves out. You can still point it at your own relay with the -turn flag. If a transfer still refuses to form, share the file another way and let junto 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.
“Apple could not verify ‘junto’ is free of malware”
junto isn’t Apple-notarized yet, so macOS Gatekeeper can block the very first launch. The one-line installer and the Homebrew cask clear this for you automatically. If you installed the .pkg or a tarball by hand, run xattr -d com.apple.quarantine $(which junto) once and reopen, or approve it under System Settings › Privacy & Security › Open Anyway.

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