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:

A Linux server or NAS on your office LAN that is always on.
A spare workstation or Mac mini in the office.
A cloud VM you control (DigitalOcean, Hetzner, a private OpenStack).
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:

aura mothership start

On first run, Aura will:

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

Output looks roughly like this:

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 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:

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 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:

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:

aura mothership status

You should see something like:

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:

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

Expected output:

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 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 for deeper diagnostics.

Joining a Peer

On a peer machine:

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

Aura will:

Resolve the URL and open a TLS connection.
Pin the server's TLS fingerprint.
Present the JWT.
Receive a peer certificate and a long-lived refresh token.
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.

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

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:

[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, scaling, join tokens.

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:

aura mothership stop

Restart (useful after config changes):

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 for exact paths and rotation.

Health Checks

Mothership exposes a simple health endpoint on its listening port:

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

Returns:

{"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:

Pick the host. See the preference order at the top of this page. Once chosen, don't move it — peers pin its TLS fingerprint.
Pick the bind address. 0.0.0.0 on a dedicated server, a specific LAN or Tailscale IP on a laptop.
Pick the port. Default is fine unless you have a conflict.
Start Mothership. Watch the output. Record the TLS fingerprint somewhere durable — password manager, team runbook, engraved on a physical plaque, whatever works.
Verify status from the host. Make sure listening is what you expected.
Verify ping from a second machine. Confirm TCP and TLS both succeed and the fingerprint matches.
Issue a test join token. Join from that second machine. Confirm peer appears in aura mothership peers.
Daemonize. See persistent daemon. Do not skip this for a real deployment.
Back up the data directory. Snapshot it nightly from day one.
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.