# Starting a Mothership

_One command turns any machine into your team's code hub._

## Overview

This page walks through starting a Mothership from scratch: choosing a host, picking an interface and port, launching the daemon, and verifying that peers can actually reach it. If this is your first time, plan on about fifteen minutes from download to a verified running Mothership.

Before you start, decide which machine will host it. Candidates, in rough order of preference:

1. A Linux server or NAS on your office LAN that is always on.
2. A spare workstation or Mac mini in the office.
3. A cloud VM you control (DigitalOcean, Hetzner, a private OpenStack).
4. A developer's laptop. This works, but the Mothership goes away when the laptop closes. Fine for bootstrapping, not for production.

The Mothership is the same `aura` binary your developers already use. There is no separate download.

## Quick Start

On the host machine:

```bash
aura mothership start
```

On first run, Aura will:

1. Generate a self-signed TLS certificate (see [TLS and JWT](/tls-and-jwt) if you want to use Let's Encrypt or an internal CA instead).
2. Generate a JWT signing keypair.
3. Bind to the default interface and port.
4. Print the join command your peers need to run.

Output looks roughly like this:

```text
aura mothership starting...
  host id:       mship_7fcd21a9
  tls:           self-signed (valid 365d)
  listening on:  0.0.0.0:7777
  join token:    eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...
  expires in:    24h

peers can join with:
  aura mothership join --url https://<this-host>:7777 \
                       --token <join-token>

Mothership is ready.
```

Leave the process running. We'll turn it into a persistent daemon in [persistent daemon](/persistent-daemon) so it survives reboots.

## Choosing an Interface

By default, Mothership binds to `0.0.0.0`, meaning "every interface on this machine." This is the right choice for a dedicated server. It is the wrong choice for a laptop on a café WiFi.

You can pin Mothership to a specific interface:

```bash
aura mothership start --bind 10.0.1.15
```

Common interface choices:

- **`0.0.0.0`**: every interface. Use on dedicated servers.
- **`10.x.x.x` / `192.168.x.x`**: your LAN address. Use if the host has both a LAN and a public interface and you only want LAN peers.
- **`100.x.x.x`**: a Tailscale address. Our recommended setup for remote teams. The Mothership is only reachable to machines on your tailnet.
- **`127.0.0.1`**: localhost only. Useful for testing. Peers cannot reach this.

> **Security callout.** Binding to `0.0.0.0` on a cloud VM with a public IP exposes Mothership to the internet. This is supported — auto-TLS and JWT are designed for it — but make sure your firewall only accepts connections from expected sources. See [troubleshooting](/mothership-troubleshooting) for common firewall issues.

## Choosing a Port

The default Mothership port is `7777`. It was chosen because it is almost never in use and easy to remember. You can pick anything you like:

```bash
aura mothership start --port 8443
```

Considerations:

- **Below 1024** (privileged ports): requires root or a capability. On Linux, `setcap cap_net_bind_service=+ep $(which aura)` lets a non-root Aura bind to 443 if you want Mothership on the standard HTTPS port.
- **Avoid conflicts**: `7777` collides with some Cisco tools; `8443` with some Tomcat installs; `4443` is usually free.
- **Single port**: Mothership uses exactly one port. All traffic — JWT handshake, sync, messages, zones — is multiplexed over it.

## Verifying It's Running

Once Mothership is up, verify from the host itself:

```bash
aura mothership status
```

You should see something like:

```text
Mothership: running
  host id:         mship_7fcd21a9
  uptime:          00:04:12
  listening:       0.0.0.0:7777
  tls:             self-signed (expires 2027-04-21)
  connected peers: 0
  pending tokens:  1 (expires in 23h57m)
  wal size:        0 B
  last error:      none
```

`connected peers: 0` is normal — no one has joined yet. The interesting line is `listening`. If you see `127.0.0.1:7777` when you meant to bind externally, something overrode your bind address (likely an environment variable or config file — check `aura config show`).

## Verifying Connectivity From a Peer

On a different machine that should be able to reach the Mothership:

```bash
aura mothership ping --url https://mothership.internal:7777
```

Expected output:

```text
ping mothership.internal:7777
  tcp connect:    ok (3ms)
  tls handshake:  ok (self-signed, fingerprint ab:cd:ef:...)
  protocol:       v1
  server id:      mship_7fcd21a9
```

The TLS fingerprint is important. Write it down. When you issue join tokens, you will include this fingerprint so peers can verify they are talking to the right Mothership and not a man-in-the-middle — see [TLS and JWT](/tls-and-jwt) for details.

If `ping` fails:

- `tcp connect: refused` — firewall or Mothership is not actually listening on that interface. Re-run `aura mothership status` on the host to confirm.
- `tcp connect: timeout` — firewall silently dropping packets, or wrong IP.
- `tls handshake: error` — clock skew between peer and Mothership, or a middlebox terminating TLS. Try from another network.

See [troubleshooting](/mothership-troubleshooting) for deeper diagnostics.

## Joining a Peer

On a peer machine:

```bash
aura mothership join \
  --url https://mothership.internal:7777 \
  --token eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...
```

Aura will:

1. Resolve the URL and open a TLS connection.
2. Pin the server's TLS fingerprint.
3. Present the JWT.
4. Receive a peer certificate and a long-lived refresh token.
5. Register this machine's peer ID with the Mothership.

Join tokens are one-shot by default: once used, they cannot be reused. This matters — do not paste a join token into a shared Slack channel expecting to hand it out multiple times. For multi-seat onboarding, see the bulk issuance flow in [join token security](/join-token-security).

After joining, the peer's `aura status` will show the Mothership:

```text
Team:
  mothership:   mship_7fcd21a9 (mothership.internal:7777)
  peer id:      peer_0a1b2c3d
  peers online: 3
  pending pull: 0
```

## Configuration File

Command-line flags are convenient for first boot. For anything long-lived, put your settings in `~/.config/aura/mothership.toml` (Linux/macOS) or equivalent:

```toml
[mothership]
bind = "0.0.0.0"
port = 7777
display_name = "Acme Core Mothership"

[tls]
mode = "self-signed"
# or: mode = "letsencrypt", domain = "mothership.acme.com"

[jwt]
default_expiry = "24h"
max_expiry     = "30d"

[limits]
max_peers           = 500
max_wal_size       = "2GB"
```

Keys described in further detail under the relevant pages: [TLS and JWT](/tls-and-jwt), [scaling](/scaling-mothership), [join tokens](/join-token-security).

> **Gotcha.** If both the config file and a CLI flag specify `--port`, the CLI flag wins. This is useful for one-off overrides but can be confusing when debugging. `aura mothership status` always shows the effective port.

## Stopping, Restarting, and Logs

Stop:

```bash
aura mothership stop
```

Restart (useful after config changes):

```bash
aura mothership restart
```

Logs in the foreground launch stream to stdout. When running as a daemon, logs live in the platform-standard location; see [persistent daemon](/persistent-daemon) for exact paths and rotation.

## Health Checks

Mothership exposes a simple health endpoint on its listening port:

```bash
curl -k https://mothership.internal:7777/healthz
```

Returns:

```text
{"status":"ok","host_id":"mship_7fcd21a9","uptime_s":252}
```

`-k` is only needed if you're using a self-signed certificate and haven't added it to your system trust store. The health endpoint is intentionally unauthenticated — it is safe to expose to load balancers and monitoring systems — but it deliberately reveals no internal state beyond uptime and host ID.

## First-Boot Checklist

A short list to run through on day one, before you hand out tokens to the rest of the team:

1. **Pick the host.** See the preference order at the top of this page. Once chosen, don't move it — peers pin its TLS fingerprint.
2. **Pick the bind address.** `0.0.0.0` on a dedicated server, a specific LAN or Tailscale IP on a laptop.
3. **Pick the port.** Default is fine unless you have a conflict.
4. **Start Mothership.** Watch the output. Record the TLS fingerprint somewhere durable — password manager, team runbook, engraved on a physical plaque, whatever works.
5. **Verify `status` from the host.** Make sure `listening` is what you expected.
6. **Verify `ping` from a second machine.** Confirm TCP and TLS both succeed and the fingerprint matches.
7. **Issue a test join token.** Join from that second machine. Confirm peer appears in `aura mothership peers`.
8. **Daemonize.** See [persistent daemon](/persistent-daemon). Do not skip this for a real deployment.
9. **Back up the data directory.** Snapshot it nightly from day one.
10. **Write down the fingerprint and host ID** for future operators. They will need them.

If you can check all ten, you are ready to invite the rest of the team.

## A Word on Hostnames

Pick a stable hostname before anyone joins. Join tokens embed the URL you give peers — if today's URL is `https://10.0.1.15:7777` and next month you move the Mothership to a different IP, every peer has to re-pin.

Use DNS. `mothership.acme.internal` or similar, with a CNAME or A record you control. You can change the IP address behind the name freely; as long as the TLS cert and fingerprint stay the same, peers are happy. This is also why we recommend Let's Encrypt (with DNS-01) or an internal CA for anything longer-lived than a week.

## Next Steps

- [Issue join tokens for your team](/join-token-security)
- [Harden TLS for production](/tls-and-jwt)
- [Turn Mothership into a persistent daemon](/persistent-daemon)
- [Pick a team topology](/team-topology)
- [Diagnose connection problems](/mothership-troubleshooting)