# 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](/install-linux) covers the systemd deployment and the [Docker guide](/install-docker) 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: ```bash 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: ```bash 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: ```bash 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//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: ```bash 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: ```bash 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: ```bash 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: ```bash aura zone claim src/parser/ --duration 2h --message "Refactoring expression parser" ``` Release it early: ```bash 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. ```bash 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: ```bash aura sentinel send --to claude-2 "Releasing zone src/parser/, you can take it" aura sentinel inbox ``` See the [Sentinel overview](/sentinel-overview) for more. ## Day-to-day commands The commands you will use most often after joining: ```bash 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 # reserve some files aura zone release aura msg list # read team messages aura msg send --to "..." 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 ```bash 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//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 ` on the Mothership side if a laptop is lost. The next sync attempt from that session key will be refused. ## Next steps - [Read the full Mothership overview](/mothership-overview) for the operational model. - [Sentinel overview](/sentinel-overview) if you coordinate AI agents across a team. - [CLAUDE.md protocol](/claude-md-integration) — how Claude Code respects team zones and messages. - [Troubleshooting](/troubleshooting-install) for connection and sync issues.