muse hub — MuseHub Fabric Connection Reference

The hub is not just a remote. It is the primary identity fabric — the shared coordination layer where authentication, plugin discovery, and multi-agent state synchronisation come together.

Table of Contents

1. Hub vs. Remote
2. Commands
   • muse hub connect
   • muse hub status
   • muse hub disconnect
   • muse hub ping
3. HTTPS Enforcement
4. Redirect Refusal
5. Configuration
6. Typical Setup Workflow

Hub vs. Remote

Muse uses two distinct concepts for network connections:

A repository has at most one hub. It may have many remotes. When you muse push to a remote that lives on the same MuseHub instance as the configured hub, the hub's token is used automatically.

Commands

muse hub connect

Attach this repository to a MuseHub instance.

muse hub connect <URL>

Arguments:

What connect does:

1. Normalises the URL (see HTTPS Enforcement).
2. Warns if the repo is already connected to a different hub.
3. Writes [hub] url = "<url>" to .muse/config.toml.
4. If an identity already exists for this hub in ~/.muse/identity.toml, shows the stored name and type.
5. If no identity exists, prompts to run muse auth register.

Does not modify ~/.muse/identity.toml — use muse auth register to authenticate after connecting.

Examples:

# With full HTTPS URL
muse hub connect https://musehub.ai

# Bare hostname — HTTPS added automatically
muse hub connect musehub.ai

# Switch hubs (warns before overwriting)
muse hub connect https://staging.musehub.ai

muse hub status

Show the hub connection and identity for this repository.

muse hub status [--json]

Options:

Human-readable output:

  Hub
    URL:       https://musehub.ai
    Type:      human
    Name:      Alice
    ID:        usr_abc123
    Token:     set (MSign ***)
    Caps:      read:* write:midi

JSON output (--json):

{
  "hub_url": "https://musehub.ai",
  "hostname": "musehub.ai",
  "authenticated": true,
  "identity_type": "human",
  "identity_name": "Alice",
  "identity_id": "usr_abc123"
}

When no identity is stored, authenticated is false and no identity fields appear.

Agent pattern:

muse hub status --json | jq .authenticated

muse hub disconnect

Remove the hub association from this repository.

muse hub disconnect

Removes [hub] url from .muse/config.toml. Credentials in ~/.muse/identity.toml are preserved — use muse auth logout to remove them as well.

Examples:

# Remove hub association only
muse hub disconnect

# Remove hub association + credentials
muse hub disconnect
muse auth logout --hub https://musehub.ai

muse hub ping

Test HTTP connectivity to the configured hub.

muse hub ping

Sends GET <hub_url>/health and reports the result.

Exit codes:

Examples:

muse hub ping
# Pinging musehub.ai… ✅ HTTP 200 OK

muse hub ping
# Pinging staging.musehub.ai… ❌ timed out

# Use in a healthcheck script
muse hub ping || notify-send "MuseHub unreachable"

HTTPS Enforcement

All hub URLs are required to use HTTPS. The _normalise_url() function:

• Adds https:// when no scheme is present.
• Raises ValueError (shown as a user-facing error) when an explicit http:// scheme is given.

# These are all equivalent
muse hub connect musehub.ai
muse hub connect https://musehub.ai
muse hub connect https://musehub.ai/

# This is rejected — signing identitys must not travel over cleartext HTTP
muse hub connect http://musehub.ai
# ❌ Insecure URL rejected: 'http://musehub.ai'
#    MuseHub requires HTTPS. Did you mean: https://musehub.ai

The HTTPS enforcement is a hard requirement, not a preference. Signing identitys are authentication credentials — sending them over cleartext HTTP exposes them to any network observer between the agent and the hub.

Redirect Refusal

The ping command uses a custom _NoRedirectHandler that refuses all HTTP redirects. When the hub returns a 3xx response:

❌ Redirect refused (301): hub redirected to 'https://other.host/'.
   Update the hub URL.

Why this matters:

A hub that silently redirects GET /health to a different host is misleading about what was actually reached. More importantly, allowing redirects on the push and fetch paths would cause the Authorization: MSign header to be forwarded to the redirect destination — potentially a different host entirely.

If your MuseHub instance redirects (e.g. from www.musehub.ai to musehub.ai), update the hub URL to the final destination:

muse hub connect musehub.ai  # not www.musehub.ai

Configuration

Hub connection state is stored in .muse/config.toml:

[hub]
url = "https://musehub.ai"

This file is per-repository and may be committed to version control — it contains only the hub URL, never any credentials. Credentials live in ~/.muse/identity.toml (see auth.md).

Typical Setup Workflow

New repository

# 1. Initialise
muse init --domain midi

# 2. Connect to hub
muse hub connect https://musehub.ai

# 3. Authenticate
muse auth register

# 4. Add the remote (MuseHub creates it on first push)
muse remote add origin https://musehub.ai/repos/my-song

# 5. First push
muse push origin -u

Cloned repository

muse clone sets the origin remote automatically. Connect the hub separately if you want muse hub status to work:

muse clone https://musehub.ai/repos/my-song
cd my-song
muse hub connect https://musehub.ai
muse auth register  # if not already logged in on this machine

CI/CD agent

# In the pipeline environment
muse hub connect https://musehub.ai
muse auth keygen --hub https://musehub.ai
muse auth register --hub https://musehub.ai --handle "ci-agent-${BUILD_NUMBER}" --agent
muse push origin

See also:

• docs/reference/auth.md — muse auth register/whoami/logout
• docs/reference/remotes.md — muse push/fetch/clone
• docs/reference/security.md — security architecture