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:
- jj-musubi, which provides the
musubicommand. See Install jj-musubi. jjandgit.- ssh access from every machine to the hub 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.