Share projects between hubs¶

A project relay gives you a local copy of a shared project and can pass that project on to your other devices. Each daemon keeps its own database. You can read and edit locally while disconnected; changes synchronize when the daemons can reach each other again.

Availability: project relays require Kata 0.19.0 or later on every participating daemon. The connection preview checks the upstream daemon's protocol support.

Choose the shape you need¶

Connect directly to a root hub when you only need a local replica. Add an intermediate relay when several devices should reach the project through your own hub:

Root hub: shared-project
          ↕
Personal hub: shared-replica
              --serve-downstream
          ↕
Device: work-project (leaf)

The root owns the project's authoritative history, signing key and lease decisions. The personal hub is a spoke of the root and a hub for the device. A leaf has an upstream connection and does not serve the project onward. These are roles for one project: the same daemon can root one project, relay another and keep others private.

Each path supports up to eight hubs, including the root, plus one final leaf.

The names above may differ, but all three copies retain the same project UID. Only the selected project travels over each connection. Workspace paths and aliases stay local. A relay does not grant access to the hub's other projects.

Use a remote daemon when every client needs to read and write one central copy. See Sharing models for the other choices.

Before connecting¶

You need:

• An existing, federation-enabled project on the upstream hub. Its operator can enable it with kata federation enable --project shared-project, using an ordinary account with project access in identity mode.
• A writable ordinary account token from that hub, issued with kata tokens create. The account must have access to the project. Expiring account tokens are accepted while valid; expiry suspends sync until the credential is replaced. A daemon bootstrap token, an issue-scoped token or an existing enrollment token cannot take its place. See Identity tokens and Team visibility.
• Owner access to the daemon receiving the replica. Bridge administration uses the owner CLI or API; an ordinary browser session cannot connect a bridge.
• An unused local project name. Connect creates the replica; do not run kata init with that name first. An unrelated project with the same name is a collision, even if its issues look identical.

Check the checkpoint capacity before choosing this for a large, long-lived project. Recovery currently needs a checkpoint that fits in 64 MiB, and retained receipts impose a growing floor on its size. Normal synchronization does not enforce that size limit. Acknowledged delivery records also remain until the binding ends, so disk usage grows with traffic and the number of downstream replicas.

Connect the receiving daemon¶

Run these steps on the daemon that will hold the new replica. In the example, that is the personal hub. Its upstream root is called team-hub in its catalog.

--daemon selects the daemon you are administering. --hub-daemon selects an upstream entry in that daemon's catalog. Keep those two targets distinct, especially when administering a remote daemon.

1. Configure the upstream account¶

Add this entry to the receiving daemon's <KATA_HOME>/config.toml:

[[daemon]]
name = "team-hub"
url = "https://hub.example"
token_env = "KATA_TEAM_HUB_TOKEN"

Provide KATA_TEAM_HUB_TOKEN to the receiving daemon process through its service environment, then restart that daemon to load the catalog. Exporting the variable only in a CLI shell does not update an already running daemon. Keep the actual token out of repository files and agent transcripts.

Use a root HTTP(S) origin, with no path prefix. Non-loopback plain HTTP needs the catalog's explicit allow_insecure opt-in for a trusted private network; redirects are rejected. See Daemon configuration.

2. Preview the connection¶

kata federation bridge connect --project shared-replica \
  --hub-daemon team-hub --hub-project shared-project \
  --serve-downstream --as local-member --preflight

Check the upstream project and account, the local account, and the bidirectional direction. Preview contacts the hub but does not enroll or create the replica. Omit --serve-downstream if this daemon will be a leaf. --as records the local account; it does not change the account authenticated by the upstream token.

If the hub requires request signing, include the signing-source flags in both preview and connect. After connecting, register the key for the new enrollment on the hub. Follow Bridge request signing for the flags and registration order.

3. Connect with the same choices¶

kata federation bridge connect --project shared-replica \
  --hub-daemon team-hub --hub-project shared-project \
  --serve-downstream --as local-member

The daemon saves a separate, project-scoped transport credential and starts bidirectional sync. It keeps the upstream account token on this daemon; neither the CLI response nor a downstream device receives it. If the response is lost, repeat the same command to resume the retained enrollment.

4. Check progress¶

kata federation bridge status --project shared-replica --json
kata federation status --json

Bridge status reads locally recorded state; connected is not a fresh hub health check. Inspect sync timestamps and pending work before treating the replicas as caught up. Use --agent for concise agent output, or --json when a script needs the full diagnostics. The web project's Refresh sync action also reads the recorded project state.

To bind a workspace to the replica after connection, run kata init --project shared-replica in that workspace. In identity mode, use an ordinary account with project access for this command and issue work; the bootstrap credential used for administration cannot perform attributed writes.

Add a device below the relay¶

On the personal hub, configure identity tokens and issue an ordinary account token with access to shared-replica. On the device, configure a catalog entry named personal-hub with that token and the personal hub's URL. Then repeat the preview and connect steps, changing the selectors:

kata federation bridge connect --project work-project \
  --hub-daemon personal-hub --hub-project shared-replica \
  --as device-member --preflight
kata federation bridge connect --project work-project \
  --hub-daemon personal-hub --hub-project shared-replica \
  --as device-member

The device is a leaf because these commands omit --serve-downstream. It needs an account on the personal hub, not the root's account token. To add another relay below the personal hub instead, its upstream token must belong to the local account that connected the personal hub's bridge. Other authorized members may enroll leaves.

What sync means for your work¶

Edits travel upstream and accepted changes travel downstream. A nearby relay acknowledging an edit means that hop has stored it. The root's signed receipt confirms root acceptance; pending push counts wait for that receipt.

Issue and comment creation show one of three states:

These states describe attribution, not review or approval of the work. Source actor and teammate labels remain visible while proof is pending. For work forwarded through the personal hub, the root records that hub's upstream account as accountable. The device's source labels remain separate.

Ordinary edits are local-first. Leases offer optional coordination; they are not a prerequisite for every edit. Reads can be stale, and concurrent changes have consistency limits. Cross-project issue moves are unsupported while either project is federated; negotiated relay projects also reject cross-project links.

Embeddings are optional. A project can select one producer and share compatible vectors so each device need not generate them again. See Sharing embedding vectors for configuration, waiting states and reuse limits. Lexical search needs no embedding provider.

Recover or disconnect¶

A bridge status of revoked means the hub refused its credential and can clear when access returns. Explicit enrollment revocation, such as kata federation revoke <id> on the hub, is permanent; the status label alone does not establish that it happened.

For a normal disconnect, finish pending deliveries and disconnect or revoke downstream enrollments first. Preview, then detach:

kata federation bridge disconnect --project shared-replica --preflight
kata federation bridge disconnect --project shared-replica

This revokes the saved upstream enrollment and keeps the local project and issues. Retry the same request after an interruption. Do not use --local-only as a routine sync repair.

The operator reference owns the full credential, retention, reset and signing rules. The technical notes explain the protocol and its trust boundaries.