A client (the aether CLI or the dashboard) must reach the server's SSH port,
:2222 by default. Git, the control channel, terminals and ssh into a session
(terminal.md) all travel over that one
connection. The server opens no HTTP port unless you set web-port
(The dashboard). Through an edge it opens no port at all.
How clients reach that port also decides how people prove who they are. Terms such as server, member and edge are in the glossary.
flowchart LR
C[Client] -->|tailnet| T[Tailscale]
C -->|GitHub sign-in| E[Edge relay]
C -->|SSH key| L["LAN, VPN or public IP"]
T --> S["Cloudfield server :2222"]
E -->|server dials out| S
L --> SWhich path to use
| Path | You need | Who can join | Each person installs | Trade-offs |
|---|---|---|---|---|
| Tailscale | The server on a tailnet | Anyone on the tailnet, once an admin approves | Tailscale and aether |
No keys or invite codes. Enables the dashboard for phones. Identity is the device owner |
| An edge | A GitHub account. No open port | Anyone invited by GitHub account | aether |
Works behind any NAT. A third party relays traffic but cannot read SSH. No server-hosted dashboard |
| LAN, VPN or public IP | A reachable host:2222 |
Anyone with an invite code | aether |
You manage SSH keys and invite codes. Keep the port behind a firewall |
All paths feed one member list, so a tailnet server can also hand an invite code to someone outside the tailnet. With no preference, use Tailscale. When neither side can reach the other (a hotel network, a server behind home NAT), use an edge.
Tailscale
Tailscale is a private network between your devices.
With the server on your tailnet, joining needs no SSH key, authorized_keys
or invite code.
On the server box, join the tailnet and print its host name:
CODEcurl -fsSL https://tailscale.com/install.sh | sh sudo tailscale up tailscale status --selfGive your team the name it prints, such as
my-server.tailnet-name.ts.net.Run
sudo aether-server setup(install.md). It finds tailscaled, names its tailnet and asksUse Tailscale to reach this server. Enter answers yes; no turns tailnet sign-in off. Setup ends by printing the host name to link to.On each client, join the same tailnet and link: in the desktop app's Connect step choose Tailscale and enter that name, or run:
CODEsudo tailscale up aether link my-serverA bare host name uses port
:2222. The first link saves the host key in~/.ssh/known_hosts, sogit push aether mainworks afterwards.
[!WARNING] The server looks for the tailscaled socket once, at startup. Start Tailscale before the server, and run
sudo systemctl restart aether-serverif you add it later. Without it the server accepts SSH keys only.
Who is let in
The server asks the local Tailscale daemon who is on the other end of each
connection, as Tailscale SSH does. The tailnet login becomes the member, and the
part before the @ becomes the display name.
- The first tailnet identity to link a fresh server becomes its super admin. Until then, a first super admin SSH key is taken only over the tailnet or from the server itself, so a port 2222 open beyond the tailnet cannot be used to take super admin first.
- Everyone after that joins as a pending collaborator.
aether linkprintslinked to <server> as <name> (collaborator, pending); an admin runs: aether member approve <member-id>, and every other command fails withmembership pending admin approval; ask an admin to run: aether member approve <member-id>until one does. Roles change withaether member role(teams.md). --tailnet-auto-joinskips approval, for teams whose tailnet already is the team boundary.- Removing someone from the tailnet, or denying them the server in your
Tailscale ACLs, locks them out of this path. Their other sign-ins stay until
aether member remove <member-id>. Single sign-on covers signing the tailnet in through your identity provider.
What an attacker can and cannot do
The lookup names the owner of the device, not the person at the keyboard. Any process or OS user on a tailnet machine can connect as its owner. That is fine for a single-user laptop and wrong for a shared box. Two guards:
- A tagged node (CI runners, shared machines) gets no identity. It is refused
with
tagged tailnet node; key authentication requiredand must use an SSH key. --tailnet-require-keydemands a registered SSH key on top of the tailnet identity. Use it when you cannot guarantee single-user devices.
When the lookup fails, the server falls back to SSH keys instead of locking anyone out. A member with only a tailnet identity cannot open new connections while tailscaled is down.
| Message on the client | What happened |
|---|---|
tailnet identity unavailable; key authentication required |
The connection did not arrive over the tailnet, or tailscaled is down. Routine on LAN connections |
tailnet login <x> must also present a registered SSH key |
--tailnet-require-key is on, as aether-server setup leaves it when you answer no to its tailnet question. To undo: sudo aether-server config set tailnet-require-key false, then sudo systemctl restart aether-server |
The server's user must be able to read /var/run/tailscale/tailscaled.sock.
The shipped unit runs as root. For another user, run sudo tailscale set --operator=<user>.
Through an edge
An edge is a relay on the public internet. The server and the client both dial
out to it, so neither needs an open port, a tailnet or a copied SSH key, and
people sign in with GitHub. The project runs one at
https://edge.onaether.dev. aether-server setup turns it on when the host has
no tailscaled or you answer no to its tailnet question. You can also
run your own.
aether login # sign in with GitHub; --json prints the address and code as JSON
aether link --claim '<claim link>' # the owner, with the claim link or code aether-server setup printed
aether link '<invite link>' # anyone an admin invited, with the link the admin sent
aether status # what this computer is linked to, and the next stepA bare name such as my-server is always an SSH address. Only a server id, a
claim code or link after --claim, or a join link goes through the edge. A
claim link or code given without --claim, or any other value with ://,
fails with the form to use instead of being dialed as an address.
The server's owner sets who is let in with edge-access: account (a GitHub
sign-in is enough) or approved-devices (the default; each new device waits for
a person to approve it). SSH is end to end, so the edge cannot read it, but it
sees who connects to which server and when. The edge guide covers
the policies, what an attacker needs under each, and claiming. Invitations and
device approval are in teams.md.
Plain LAN, VPN, or a cloud box
With no tailnet and no edge, SSH keys and invite codes identify people.
The first admin
aether link 192.168.1.50:2222The first key to link a fresh server becomes the super admin. Without an edge or tailnet sign-in, until that first link any key that reaches port 2222 becomes super admin, so link right after the server starts and keep the port closed to the internet. With tailnet sign-in, the first key must arrive over the tailnet or from loopback.
The CLI offers ~/.ssh/id_ed25519 and any key in your ssh-agent, and creates
~/.ssh/id_ed25519 if it finds none. For another key:
aether link 192.168.1.50:2222 --key ~/.ssh/aether_ed25519When the server has an edge, the first super admin's key must come from a loopback address: the server itself, or an SSH tunnel to it. Anyone who can reach the port could otherwise take super admin before the owner claims the server.
ssh -L 2222:127.0.0.1:2222 <user>@<server-host> # keep it open
aether link 127.0.0.1:2222 # in another terminalFrom any other address the handshake fails and the server's message names the
claim instead: sudo aether-server edge claim-code on the server, then
aether login and aether link --claim <code> on your machine
(edge.md). Once you are admin, your key works
from any address: aether link <server-host>:2222.
link saves the path in the client's config.json (~/.config/aether/ on
Linux, ~/Library/Application Support/aether/ on macOS). git push aether
calls the system ssh instead, so add an IdentityFile line for the server
host in ~/.ssh/config. The CLI never asks for a passphrase: run ssh-add on
a protected key first. Without a usable key the handshake fails with
attempted methods [none], followed by why the key was rejected.
Everyone else
An unknown key is refused with no Cloudfield member for this key. An admin
creates a one-time code (--ttl is in seconds, default 24 hours):
aether invite --ttl 3600<invite-code>
expires <expiry-time>The teammate redeems it once, which registers their key as a collaborator and burns the code:
aether link <server-host> --invite <invite-code> --name "Example"linked to <server-host> as Example (collaborator)What an attacker can and cannot do
Every connection is authenticated by key, and a member can run code in containers on the host. Keep the port behind a firewall or a VPN, and do not open it to the whole internet on a cloud box. Treat invite codes and member keys as secrets.
The dashboard
There are two dashboards, and they are independent.
aether gui |
Server-hosted | |
|---|---|---|
| Sessions on | Your own machine, on 127.0.0.1 |
The server |
| Reaches the server | Over the same SSH link as the CLI | Directly, over HTTPS |
| Works with | Every path above | Tailscale only |
| Good for | Computers: has the directory picker and other local actions (local-gateway.md) | Phones and borrowed laptops: open a URL, already signed in |
aether gui changes nothing about the server's network shape. The
server-hosted dashboard is the server's only HTTP port, and it listens on the
host's tailnet addresses only. It needs tailscaled running before the server,
MagicDNS and HTTPS certificates enabled for the tailnet (Tailscale admin
console, DNS page), and root or the tailscaled operator to fetch the
certificate. Plain HTTP is never offered. Turn it on:
sudo aether-server config set web-port 443
sudo systemctl restart aether-serverAny device on the tailnet then opens the server's MagicDNS name, already signed
in, with no token or install: https://my-server.tailnet-name.ts.net/ (other
ports append :<port>). web-port defaults to 0, SSH only.
aether-server setup offers 443 after you answer yes to its tailnet
question, and aether-server install --web-port 443 sets it without questions.
Requests are identified by the same tailnet lookup as SSH, on every request
with no session or token. The joining, approval and role rules above apply, and
the same trust boundary: the lookup names the device owner, and tagged nodes
are refused. --tailnet-require-key and web-port exclude each other, because
a browser cannot present an SSH key. A server with no tailscaled, including
one reached through an edge, has no server-hosted dashboard. The
Android app in Tailscale mode wraps this URL and
cannot receive notifications. Its Edge mode needs no tailnet
and no web-port: it runs the local gateway on the phone and reaches the server
through the edge.
Add it to your home screen
A phone can keep the dashboard as an app that opens full screen.
- On Android, open the server URL in Chrome and pick Install app from the ⋮ menu.
- On an iPhone, open the server URL in Safari (Chrome on iOS can add it too) and pick Share → Add to Home Screen.
On iOS, Web Push works only for the installed app, and has these limits:
- iOS 16.4 or later, and the app opened from the home-screen icon. In a Safari tab Settings → Push notifications shows install steps instead of the switch; Dismiss hides them on that browser.
- The permission prompt appears when you turn the switch on, because iOS asks only after a tap.
- The icon badge shows the Needs you count while the app is open and push is on, and clears at 0. The push carries no count, so a closed app keeps the badge it last had until you open it.
Install the server URL, not an aether gui one. An aether gui URL carries a
per-process token that the home-screen icon drops, so the app opens
unauthenticated. There is no offline mode: away from the tailnet the app shows
the same connection error as the browser.
Notifications
The server-hosted dashboard can notify a device when a session of yours needs you. On that device open Settings and turn on Notify this device when a session needs me. The browser asks for permission once. Send test notification tests the whole path and shows the push service's own error when it fails. To hear about sessions on Slack instead, including on Android, see slack.md.
A notification goes to a session's owner when the session starts needing them, by the rule behind Needs you (failure-handling.md), and to every admin when a workspace's spend rises past its budget:
| The session | The notification says |
|---|---|
| asks for a permission | Permission: <action>, or Permission requested |
| asks a question | Question from the agent |
| reports that it is blocked | Blocked: <summary> |
asks you with report --outcome needs-input |
the question |
| needs you another way | Waiting for your reply, or the usage-limit reason |
| loses its Enhanced session | Enhanced could not start: <error> or Agent disconnected: <cause> |
| fails a turn or reports failure | Turn failed: <error>, Agent failed or Agent reported failure, review the result; never for an attached subsession |
| reports success | Finished: review the result, once and quietly; never for an attached subsession, whose outcome is for its parent agent |
ends failed with a result nobody has seen |
Failed, review the result |
| (admins, titled with the workspace) spend reaches the budget's warning or cap | Budget warning: $8.50 of $10.00 spent or Budget reached: $21.00 of $20.00 spent, new sessions are refused |
A working, waiting or stalled session does not notify. A Background session does not notify for a
question. One notification per
session or workspace budget: a newer one replaces the older, and tapping it opens
the session or the workspace's budget. When a session stops needing you, its
notification is replaced, silently, by No longer needs you, or No longer awaiting review for a finished session's; a push must
show something or Safari drops the subscription. While you use a dashboard on any device,
notifications wait until you have left every dashboard alone for a minute and
the session still needs you, or the budget is still where it was.
How often you are notified is your notification level
in Settings → Notifications: by default what needs you is pushed at once
and a finished or failed session waits for a digest every 30 minutes. Pushes
within 2 minutes of another join it as one quiet summary, and
quiet hours hold every push for a digest
sent when they end. An assistant card is pushed with
Review…, which opens the card where you approve it, and Decline,
where the device shows them. Runs the
assistant launched for you also notify you when
they finish, through the watch it keeps on
them.
It needs:
- The server-hosted dashboard.
aether guidoes not offer the switch. The desktop app shows its own notification while open. - A browser with Web Push: Chrome, Edge and Firefox on a computer or Android, Safari on a Mac. On an iPhone or iPad it works only in the dashboard added to the home screen, on iOS 16.4 or later. The Android app needs a UnifiedPush distributor (below).
- Outbound HTTPS from the server on port 443 to the browser vendors' push
services:
fcm.googleapis.com(Chrome),updates.push.services.mozilla.com(Firefox),web.push.apple.com(Safari) and*.notify.windows.com(Edge). The server connects directly, ignoringHTTPS_PROXY, and only to public addresses.
The server signs messages with a key it creates on first start,
<data-dir>/push/vapid_key.pem. If that file is lost, turn the switch off and
on again on each device. A refused message is logged as push: notification not delivered with the service's answer. What the push service receives is in
privacy.md.
In the Android app
The app's WebView has no Web Push, so the app subscribes itself through
UnifiedPush: a distributor app on the phone, such
as ntfy from Google Play or F-Droid, holds one connection
to its push server for every app that uses it. The switch is the same
Settings → Notify this device when a session needs me, in either
connection mode, aether gui's Edge gateway included.
Turning it on asks Android for permission to notify, then asks the
distributor for an address and Web Push keys, picking the default
distributor or showing Android's picker when there are several. The app hands
the address and keys to push.subscribe itself, as the dashboard would. The
server encrypts and signs exactly as it does for Chrome; the connector library
in the app decrypts, and the app drops any message not encrypted to its keys.
With no distributor installed the switch row says The app gets notifications through a UnifiedPush distributor, and this phone has none. Install ntfy and
turn the switch on, or, in Tailscale mode, open the dashboard in Chrome
and install it there.
A distributor that refuses shows its reason, such as The push distributor refused to register Cloudfield: ACTION_REQUIRED (sign in to it, then try
again).
An assistant card's notification follows the dashboard's rules: Review…
opens the card, where you approve it, Decline declines it without opening
the app, and a private card or one over 240 characters has no buttons. Decline needs
Tailscale mode and Android 12 or later: it calls assistant.confirm on
the server's dashboard, identified by the phone's tailnet login like any
dashboard request, and Android asks you to unlock the phone before it runs
when you tap it. A card with buttons is not bridged to a watch, but an app
you have given notification access can still press Decline for you.
Decline refuses a card from a server other than the one chosen under
Connection now, with the error This card is from <old>, and the app now connects to <new>.
Older Android cannot require that, so there, and in Cloudfield Edge mode,
where the identity is the CLI the app runs only while it is open, a card's
notification only opens it. While it runs the notification reads
Declining… with no buttons; then Declined with the card's text, or
Couldn't decline with the server's own error, which alerts and opens the
card. Tapping a notification while the dashboard is open opens its page in
place, keeping unsent drafts; a card opens over the page you are on, so Back
still returns where it did. When a session stops needing you, its
notification goes away; a card
decided or withdrawn elsewhere is replaced, silently, by how it ended, such as
Approved: <summary>.
Sessions, watches and cards that need you, and summaries of them, arrive on
the Sessions that need you channel; assistant notices, budgets and test
notifications on Assistant updates, which you can quiet separately in
Android's settings for the app.
The notifications are marked private. Whether the lock screen shows their
text is Android's setting for sensitive notifications; with it off, the lock
screen shows only what kind each one is: A session needs you, New update,
or Assistant card for a card with buttons, how a card ended, and the
outcome of declining it.
In Tailscale mode, when you choose another server under Connection, the app drops its registration at the distributor, tells the previous server to forget the phone, and registers a new address for the new server, so nothing the previous server sends reaches the phone.
Limits:
- The server posts only to public addresses. A self-hosted ntfy reachable
only on the tailnet or LAN fails with
refusing to connect to <ip>: not a public addressin the server'spush: notification not deliveredlog line. Use ntfy.sh or an ntfy server with a public address. - In Cloudfield Edge mode, switching to another server through the gateway keeps the registration on the first one, which goes on notifying the phone. Turn notifications off before you switch, and on again after.
- In Cloudfield Edge mode the server learns a new address from the distributor only while the app is open; until then notifications go to the old one, which the server drops once the push service reports it gone.
- ntfy keeps a connection open, which its authors measure at about 0-1% of battery over 17 hours. ntfy from Google Play delivers ntfy.sh messages through Firebase unless instant delivery is on.
When it does not start
If the dashboard cannot identify or encrypt, it does not start. The server keeps
serving SSH and the edge, and says why in journalctl -u aether-server
(server: the tailnet dashboard is not serving; the server runs without it)
and in Settings → Server of a dashboard opened another way. The first two
reasons are checked once at startup: fix them, then sudo systemctl restart aether-server. For the others the server retries, up to every 5 minutes, so a
server that starts before tailscaled or before HTTPS certificates are on starts
the dashboard by itself.
| Message | What to do |
|---|---|
the dashboard identifies members by tailnet WhoIs and tailscaled was not running when the server started (no /var/run/tailscale/tailscaled.sock); start Tailscale before the server, or set web-port to 0 |
Start tailscaled, then restart the server |
tailnet-require-key demands an SSH key on every tailnet connection and the dashboard cannot present one; set one of tailnet-require-key and web-port off |
Pick one |
tailscaled did not report this node: status has no DNS name |
Enable MagicDNS |
servergw: tailscaled reports no tailnet address for <name> |
The node is not up. Run tailscale status --self |
servergw: HTTPS certificate for <name>: <error>; enable MagicDNS and HTTPS certificates for the tailnet in the Tailscale admin console (DNS page), or set web-port to 0 |
Enable HTTPS certificates, or run as root or the tailscaled operator |
servergw: listen: no tailnet address could be bound: <errors> |
The port is taken on every tailnet address, or binding needs privileges the server lacks. One address that will not bind (IPv6 on a host with IPv6 off) is only a warning |
Once it serves, a request it cannot identify is refused with a JSON error:
403 tagged tailnet node; the dashboard identifies members by their tailnet login and a tagged node has none (tagged nodes use a key over SSH), or 503
tailnet identity unavailable: <error> (tailscaled is down, or the source is
not on the tailnet).
web-port is off by default because it needs tailscaled, MagicDNS and HTTPS
certificates that an existing install may lack. On a fresh config aether-server setup checks that tailscaled answers, that HTTPS certificates are on, that the
host holds its tailnet addresses (tailscaled with --tun=userspace-networking
does not) and that nothing listens on port 443. If a check fails it offers 0
and prints the fix. Typing 443 anyway still sets it, and the dashboard starts
once the tailnet is ready.
Limits
- Tailnet identity names a device owner, not a person.
- A server without tailscaled, or reached through an edge, has no server-hosted dashboard.
- Any other tunnel that gets a TCP port to the server works, but only Tailscale and the edge bring identity with them.
Next: Edge.