We’ll walk you through choosing what machine the hub will run on, sharing a repo, and adding other machines. These examples use devbox for the hub’s ssh name and app for the project. Replace them with yours.

Before you start

You need a few prerequisites on every machine:

Use a jj repo with at least one commit and complete history (shallow and partial clones are not supported). To try things out, I recommend you use a disposable clone of some project.

Install jj-musubi

Install jj-musubi on every working machine and the hub machine. The easiest way is to download an archive from the releases page and put its musubi executable on your PATH. There are builds for Linux (static), macOS and Windows, each for x86_64 and aarch64.

The release’s SHA256SUMS lists each archive’s checksum. To check that this repo’s release workflow built an archive, run gh attestation verify <archive> --repo bos/jj-musubi.

On macOS, downloads via browser will not run by default because musubi isn’t notarized. Use curl -LO, or clear the browser’s mark with xattr -d com.apple.quarantine musubi.

Choose the hub machine

Choose a machine that’s usually available and reachable over ssh, such as a devbox or home server. When it’s unavailable (e.g. sleeping, shut down), other machines can’t sync.

The hub can coexist on a machine alongside the daemons.

Connect over ssh

The hub may not know the hostname under which other machines can reach it (e.g. if you’re connecting to it over Tailscale), or you may have an ssh alias for it. musubi hub --advertise <name> tells jj-musubi your preferred hostname.

The hub’s musubi must be on the PATH of non-interactive shells. Check from another machine:

ssh devbox musubi --version

If that says musubi: command not found, put its directory on PATH in your shell’s startup file, before any line that returns early for non-interactive shells.

The first time it contacts a hub over ssh, jj-musubi will authorize an ssh key that can only talk to the hub. It will use ssh to set up that key, so ssh may ask for your password once. After that, the daemon uses this key and should never prompt.

To be very clear, jj-musubi is intended for use by just one person (and their agents). Anyone who can talk to a hub can read and write every hive on it (SECURITY.md). See SSH configuration for more details.

Start the hub

On the hub machine, start the hub interactively:

musubi hub

The hub will keep running until you stop it. Leave this terminal open for now. Once you’re satisfied that you want to continue using jj-musubi, you can manage it through a service.

When you first start a hub, it creates ~/musubi-hub for its data, and prints what to run elsewhere:

Created a new hub in /home/you/musubi-hub
To share a repository:               musubi create --hub devbox
To add another machine's copy of it: musubi join --hub devbox
To make a new copy of a hive:        musubi clone <name> [<dir>] --hub devbox
Other machines reach this hub over ssh: use the name they ssh to this machine by, if it isn't devbox.
On this machine, leave out --hub.

Start the hub with --dir to point at a different hub directory.

Share a repo

In your repo on one machine, create a jj-musubi hive from it:

musubi create --hub devbox

The hive is named after the repo’s origin remote (app for github.com/you/app), or its directory if it has no remotes. If you’d prefer a different name, just provide that: musubi create work-app.

When you add a repo to a hive, by default it does not contain undo history from before that point. To share earlier undo history too, see Bring the operation history.

create starts the daemon if it isn’t running, and returns once the repo has synced.

Add other machines

On each other machine, in its copy of the repo:

musubi join --hub devbox

The hub figures out which hive from your repo’s history and remotes; you don’t need to name it.

Joined hive app (matched remote origin), 2 machines

If the repo you’re trying to join from doesn’t match a hive, or matches more than one, join stops and says why. (See Joining is refused.)

On a machine that doesn’t yet have a copy of the repo, clone the hive. This creates a repo, joins the hive and syncs, then checks out trunk() using this machine’s jj config:

musubi clone app ~/src/app --hub devbox

A small amount of repo-local config is copied during a clone. For instance, a machine might not have name or email settings in its jj config, which is common in disposable environments used by agents.

Your first sync

If you want to see what’s going on, run:

musubi status

Look for Daemon: running, serving this repository, a recent synced ... ago, and the hub has all its work. musubi status doesn’t contact the hub, so it should return immediately even if e.g. your laptop isn’t on a network.

Let’s say you’re on a laptop. To see a sync happen, edit some files, then run jj status to snapshot those edits. You can then either wait a moment or run musubi sync to be sure the send part of a sync has completed.

On another machine, either wait a moment or run musubi sync to ensure that the receive side of the sync has completed, then run jj log. The laptop’s in-progress commit should appear as laptop/default@, using the machine name from musubi status. You can inspect its contents using jj diff -r laptop/default@. jj-musubi won’t update your working copy, so nothing changes until you pick up the work.

I almost never run musubi sync by hand. It’s occasionally convenient for debugging, because it will report holds and failures. For a hold or other warning, see Troubleshooting.

Keep the hub running

So you’ve decided to use jj-musubi for real. Stop the foreground hub, then install a service that will start it now and at login:

musubi hub install

This installs a launchd agent on macOS or a systemd user unit on Linux, and that will restart the hub if it fails. (Windows has no hub install.)

To start the hub at boot and keep it running after logout, on macOS or Linux:

musubi hub install --at-boot

Run this as your normal user, without sudo. It will ask for administrator permission to install and manage the service as you, using your home and state directory. On macOS this installs a launchd daemon; on Linux, a systemd system unit.

Without --at-boot, macOS needs a logged-in user session. This is also the default on Linux, but you can keep the login service running using loginctl enable-linger (N.B. that command will affect all of your user services).

On macOS, the hub logs to hub.log in jj-musubi’s state directory. On Linux, use journalctl --user -u musubi-hub for a login service, or sudo journalctl -u musubi-hub-$(id -u).service for a boot service.

musubi hub uninstall stops the hub and removes the service.

Start the daemon at login

create, join and clone start the daemon. To start it at login too:

musubi daemon install

This starts the daemon and installs a launchd agent on macOS, a systemd user unit on Linux, or a Windows Run registry entry. The user-service requirements apply.

Optional clone defaults

Depending on how you like to work, it can be convenient to choose which jj and jj-musubi settings future clones can inherit. Name and email are the defaults.

jj config set --repo musubi.clone-config '["user.name", "user.email", "aliases.l"]'

I recommend auto-configuring only portable settings. For instance, signing keys, tool paths and watchers shouldn’t be shared because they’ll probably cause you headaches. See musubi.clone-config for override rules and behaviour when a hive is recreated.

Naming machines

When a repo is managed by musubi, jj shows each machine’s working copy as a workspace named after the machine, such as laptop/default@ (@ = “the working copy”, default = “the default workspace”, laptop/ = “on the machine named laptop”).

The machine name defaults to jj’s operation.hostname, usually its hostname, and these are often horrendously long and unfriendly. To choose a friendlier or shorter name, pass --machine to create, join or clone:

musubi join --machine work-laptop

If you somehow set up multiple machines with the same name (but why?), they’ll be given unique suffixes, such as laptop-1a2b/default@ and laptop-3c4d/default@. This also takes care of such odd situations as you deciding to name a normal jj workspace laptop/default.

Sharing complete operation history

By default, creating or joining doesn’t share undo history from before that time. (If you speak the jargon, each machine’s jj op log, as shared to other machines, starts from the time it joined). This keeps snapshots and commits that are unlikely to be helpful from cluttering the hive.

If you want to share the whole operation history, use musubi create --full-history --hub devbox, or pass --full-history to join.