Getting started

Running in a couple of minutes.

One command to install, one to launch. Peers on your network show up on their own.

Install

Quick install

macOS · Linux

Windows · PowerShell

This downloads the release for your platform and installs to ~/.local/bin on Linux and macOS, or %LOCALAPPDATA%\MeshTalk on Windows.

Options

--non-interactive   accept all defaults
--version TAG      install a specific release
--install-dir DIR  choose where it lands
--prerelease       include pre-releases
--dry-run          preview without installing
--uninstall        remove MeshTalk

Manual install

Download the .tar.gz for your platform from the latest release, extract it, and run ./meshtalk. The archive carries everything: no Python, Bun, or package manager at runtime.

Quick start

# launch the TUI; it starts an attached backend
$ ./meshtalk
# Ctrl+P opens commands
# peers on your LAN appear on the left

MeshTalk keeps its state in ~/.meshtalk. Override that location with the MESHTALK_DATA_DIR environment variable.

Remote setup

For peers on different networks, point MeshTalk at a control service. Press Ctrl+P in the TUI and choose Control server, or set it from the CLI.

MeshTalk prefers direct UDP and falls back to the relay when direct setup fails. While relayed it keeps probing and switches back once the new path is authenticated. LAN TCP stays the highest-priority path.

note Production control services must use wss://. Plain ws:// is accepted only for localhost development.

Group chats

# create a named room
$ meshtalk room create "Project team"
✓ invite copied to clipboard

# share the invite, then on the other device
$ meshtalk room join 'meshtalk-group:…'

# send a message
$ meshtalk group_send "Project team" "Hello team!"

Each message is encrypted independently for every member. There is no shared group key, and offline members receive queued delivery when they return.

Docker

# pull the images
$ docker pull ghcr.io/qincai-rui/meshtalk/control:latest
$ docker pull ghcr.io/qincai-rui/meshtalk/client:latest

# run the control service
$ docker compose up -d

# open a client
$ docker compose run -it client

Build from source

Building needs Bun and uv.

$ git clone https://github.com/QinCai-rui/MeshTalk.git
$ cd MeshTalk
$ bun install
$ bun run meshtalk

Update

# update this installation
$ ./meshtalk update --install

# update another directory
$ ./meshtalk update --install --dir /path/to/MeshTalk

Updates track QinCai-rui/MeshTalk by default. Point them elsewhere with meshtalk update repo.