Join a shared rig

You received an invite URL. Now:

rig login                              # one-time, if not already signed in
mkdir my-shared-rig && cd my-shared-rig
rig join <invite-url>

rig join is self-authorizing — the URL is the consent — so it works even if your local rig has [sync] enabled = false. You can also join from an existing directory, but it must be empty or be a checkout of the same rig — see Joining a non-empty directory.

Pure-capability invites (the owner minted them with --ops, no role) work without a Hub account:

rig join <invite-url> --anonymous

What it does

1. Validate the invite against the relay. Refused if expired, revoked, exceeded uses, or scoped to a different email.
2. Consume the invite (decrements --max-uses).
3. Provision a device for your machine. Writes .rig/tap-binding.local.json with your secret. Mode 0600. Never commit.
4. Initial sync — fetch every shared file from the relay and write it locally.
5. Start the daemon — tapd runs in the background, applying further changes as they arrive.

After join, you can:

rig status             # confirm
rig install            # set up env, dirs, etc. (the rig.toml just synced in is now active)
claude                 # start working

Flags

Prerequisites

You need three things:

1. @rigxyz/tapd installed on your machine: npm install -g @rigxyz/tapd.
2. @rigxyz/cli installed: npm install -g @rigxyz/cli.
3. A signed-in Rig Hub account — run rig login once per machine. (You can skip this for pure-capability invites; pass --anonymous.)

rig join will fail with a clear error if tapd isn't on PATH or if you're not signed in (and the invite requires identity).

What you get

After join, your directory contains:

• rig.toml — the rig's manifest.
• All shared files from [package].include.
• .claude/ — skills, settings, etc.
• .rig/tap-binding.local.json — your device's binding state.
• .rig/instance.toml — install metadata.

What you don't get:

• The owner's .env (env vars are never synced).
• Contents of [local].dirs (those folders are created but empty).
• Anything in the default-excluded paths.

Joining a non-empty directory

If you're rejoining (e.g. you rig disconnected previously), rig join recognises an existing checkout and reconciles — re-establishing the binding without re-downloading everything. Files in your local copy that differ from the relay state count as edits and will be sent on the next sync.

If you're joining into a non-empty directory that isn't the same rig, rig join refuses. Start from a clean directory instead.

After join

• Your edits to shared files propagate to the rest of the team.
• Their edits show up in your filesystem in near-real-time.
• Files outside [package].include stay strictly local.

Troubleshooting

See Daemon for daemon-level troubleshooting.

See also

• Invite — the other side of this flow.
• Daemon
• Recovery — if a teammate deletes something.