Connect to a Mothership

Get a join token, run one command, and watch function-level changes flow between teammates in real time.

A Mothership is Aura's team hub. It is a single process, run on a server or someone's laptop, that coordinates function-level change sync, cross-branch impact alerts, team messaging, and agent collision detection across everyone working on a repository. Connecting a developer machine to a Mothership takes one command. This guide walks through the complete flow: getting a join token, running the client command, verifying the connection, and observing your first real-time sync.

If you have not yet set up a Mothership, the Linux install guide covers the systemd deployment and the Docker guide covers a Compose setup. The rest of this page assumes someone on your team has a Mothership running and can generate join tokens.

Prerequisites

  • Aura installed on your machine (aura --version works).
  • The target repository initialized with aura init.
  • Network reachability to your Mothership's host and port (default 7777, or 443 if fronted by a TLS reverse proxy).
  • A join token from whoever runs your team's Mothership.

Getting a join token

Tokens are generated on the Mothership host. If you run it yourself:

aura team invite --expires 24h

The output looks like:

Team: acme-backend
Invite token (expires in 24h):

  aura1:acme-backend:v1:eyJlbmRwb2ludCI6Imh0dHBzOi8vbW90aGVyc2h...

Share this token with your teammate. They run:

  aura team join aura1:...

This token grants full member access. Treat it like a password.

Tokens are self-contained: they encode the Mothership endpoint, a keying secret for the initial handshake, and the team identifier. Tokens are single-use unless --reusable is passed (discouraged), and they expire — --expires 1h for a tight window, --expires 7d for an onboarding email.

For tighter control, tokens can be bound to an email or GitHub handle:

aura team invite --expires 24h --email alice@example.com

If someone else joins with a token bound to alice@example.com but authenticates as a different identity, the Mothership rejects the join. This only matters for teams that wire identity into the Mothership; small teams typically skip it.

Joining from the client

On your laptop, from inside the Aura-initialized repository:

aura team join aura1:acme-backend:v1:eyJlbmRwb2ludCI6...

What happens:

  1. The token is parsed locally. The endpoint, team ID, and keying secret are extracted.
  2. Aura dials the endpoint and performs a handshake using the token's keying secret.
  3. The Mothership verifies the token (not expired, not already used, scoped to this team).
  4. A long-lived session key is negotiated and stored at ~/.aura/teams/<team-id>/session.key.
  5. The repository is registered against the team; .aura/team/zones.json is populated with current zone claims, and the live-sync ledger is opened.
  6. The client starts a background sync daemon that stays connected for the lifetime of the shell.

On success:

Joined team: acme-backend
Endpoint:    mothership.acme.com:7777
Session:     established
Teammates online: 4 (alice, bob, charlie, d-agent)
Live sync:   active

If the handshake fails, you will see a specific error — expired token, wrong team, wrong endpoint. Most failures are token typos or tokens that expired while sitting in an email. Ask for a fresh one.

Multiple teams, multiple Motherships

Aura supports joining more than one team. Each join records a separate session under ~/.aura/teams/, and each repository is registered against exactly one team. You can switch a repo between teams by running aura team leave and then joining a different one.

A single developer might:

  • Belong to acme-backend for their primary work repo.
  • Belong to open-source-project for a side contribution.
  • Belong to sentinel-agents for a shared AI-agent coordination hub.

Each connection is isolated; tokens do not cross-pollinate.

Verifying the connection

Immediately after joining:

aura team status

You should see:

Team: acme-backend
Endpoint: mothership.acme.com:7777
Session: connected (ping 34ms)
Teammates online: 4

Current zones:
  src/auth/         → alice (claimed 2h ago)
  src/parser/       → bob (claimed 14m ago)
  src/tests/        → unclaimed

Pending sync: 0 incoming, 0 outgoing
Unread messages: 0

ping is the round-trip time to the Mothership. Anything under ~100ms is fine for interactive use.

For a health check of the sync pipeline itself:

aura live-sync-status

This shows the in-flight state of the function-level sync: how many functions your client has outgoing (waiting to be pushed), how many are incoming (waiting for you to pull), and which functions have been modified upstream since your last pull. In steady state all three numbers are zero.

Your first real-time sync

Ask a teammate to modify a function in the shared repository and run aura save. Within a couple of seconds, your side should show:

🔄 SYNC: 1 function update available

Pull it:

aura live-sync-pull

Aura fetches the function body from the Mothership and applies it at the AST level in your working tree. Not the whole file — just the function. If you were in the middle of editing a different function in the same file, your edit is preserved. This is one of the features that distinguishes function-level sync from a file-level tool.

On the other side, if you run aura save, your teammate sees the same notification. The push happens automatically as part of aura save (or as part of aura_log_intent when an agent is committing). There is no "press push" step.

Team zones

Before editing a file, Aura checks the Mothership for any active zone claim on it. A zone is a soft reservation a teammate has taken out on a file or directory, signaling "I'm working here, heads up."

If you try to edit a file that is in someone else's zone, Aura surfaces a warning:

🚨 TEAM ZONE WARNING
File src/auth/hash.rs is claimed by alice (expires in 2h).
Proceed with caution or coordinate first.

If the zone is marked BLOCKED instead of WARNING, the edit is refused until you talk to the claimer or they release the zone. Zones are a coordination aid, not a lock — they exist because merge conflicts that happen at 5pm on a Friday are much better avoided by a Slack message at 11am.

Claim a zone of your own:

aura zone claim src/parser/ --duration 2h --message "Refactoring expression parser"

Release it early:

aura zone release src/parser/

Zones expire automatically. The Mothership cleans them up.

Team messaging

The Mothership also carries short messages between teammates and between AI agents.

aura msg send --to alice "Heads up, about to touch the auth tests"
aura msg list

Messages are ephemeral — they live until read, then are archived for a short window. They are not a replacement for Slack or email; they are a way for the tooling to send coordination notes, and for humans to reply inside the same channel.

AI agents have their own inbox via the Sentinel subsystem:

aura sentinel send --to claude-2 "Releasing zone src/parser/, you can take it"
aura sentinel inbox

See the Sentinel overview for more.

Day-to-day commands

The commands you will use most often after joining:

aura team status           # where do I stand?
aura live-sync-pull        # pick up teammate changes
aura live-sync-status      # what's in flight?
aura zone claim <path>     # reserve some files
aura zone release <path>
aura msg list              # read team messages
aura msg send --to <user> "..."
aura live-impacts          # cross-branch impact alerts

The most important habit is to run aura live-sync-pull before you start editing. Most changes you need will already have arrived via the background daemon, but the explicit pull is idempotent and catches anything the daemon missed during a disconnect.

What gets synced, what does not

The Mothership transmits function bodies and metadata about change. Specifically:

  • Added, modified, or deleted functions, methods, and classes in tracked languages.
  • Intent log entries (so teammates see why you made a change, not just what).
  • Zone claims and releases.
  • Messages and sentinel traffic.
  • Session presence (who is online).

The Mothership does not transmit:

  • Full file contents for files that Aura cannot parse (binaries, unknown languages).
  • Git history. The Mothership is not a Git remote. Push your Git branch to GitHub or wherever you normally push.
  • Configuration files, .env files, or anything that is not code.
  • Your local cache or session state.

If your team needs full-file sync of arbitrary files, that is a Git responsibility. The Mothership fills the gap between "every keystroke synced like a Google Doc" (too much) and "push once a day like a Git PR" (too little) for the specific case of code logic.

Disconnecting

aura team leave

This terminates the session, discards the session key, and unregisters the repository from the team. The Mothership notes your departure; teammates see you drop from the online list within a few seconds.

Your local .aura/ state is preserved, minus the team-specific subdirectories. You can rejoin later with a fresh token.

Security notes

  • Tokens are credentials. Do not paste them in public chat, do not commit them, and prefer short expirations.
  • Session keys live at ~/.aura/teams/<team-id>/session.key. Protect that directory like you would an SSH key.
  • Traffic is end-to-end encrypted between client and Mothership using the session key negotiated at join time. A compromised reverse proxy in front of the Mothership cannot read function bodies.
  • The Mothership itself sees your function bodies in plaintext (it needs to, for sync and impact analysis). If you run a shared Mothership, treat its host as sensitive as a code review server.
  • Revoke access with aura team revoke <member> on the Mothership side if a laptop is lost. The next sync attempt from that session key will be refused.

Next steps

Up next

Install Troubleshooting

Common errors, permissions, PATH, hook installation, and how to recover.