How operation services work

Planned for Waveshift 0.5

This page describes how per-operation chat and map services are designed to work. See What's coming for the overview.

An operation runs on its own Egress Server (also known as a PoP, point of presence): a private network that someone creates for that operation. Each Egress Server can have its own private messaging (Matrix) and situational awareness (TAK) servers. Only the people added to that Egress Server can reach them, and they are deleted together with it when the operation ends.

1. The big picture

Each Egress Server is a self-contained bubble: its own VPN, its own TAK server, its own Matrix server. The console creates and removes them.

flowchart TB
    console["Waveshift Console"]

    subgraph popA["Egress Server: Kestrel"]
        direction TB
        vpnA["VPN entry point"]
        takA["TAK server"]
        mxA["Matrix server"]
        vpnA --> takA
        vpnA --> mxA
    end

    subgraph popB["Egress Server: Osprey"]
        direction TB
        vpnB["VPN entry point"]
        takB["TAK server"]
        mxB["Matrix server"]
        vpnB --> takB
        vpnB --> mxB
    end

    console -- "creates and deletes" --> popA
    console -- "creates and deletes" --> popB

    alice["Alice's devices"] -- "Kestrel VPN" --> vpnA
    bob["Bob's devices"] -- "Osprey VPN" --> vpnB

2. Creating an Egress Server

The person creating an Egress Server chooses who is in it and which services it has. Everything else is automatic.

sequenceDiagram
    actor owner as Egress Server owner
    participant console as Waveshift Console
    participant pop as New Egress Server
    actor user as Team member

    owner->>console: Create Egress Server "Kestrel"
    owner->>console: Pick team members from the user list
    owner->>console: Choose services (TAK, Matrix)
    console->>pop: Build the VPN, TAK server and Matrix server
    console->>pop: Create a VPN config, TAK login and Matrix account for each member
    console-->>owner: Egress Server ready
    user->>console: Log in
    console-->>user: Kestrel bundle (VPN config, TAK data package, Matrix login)

3. What each person receives

For every Egress Server they are in, a person gets one bundle. Everything in it belongs together and is labelled with the Egress Server's name.

flowchart LR
    bundle["Kestrel bundle"]
    bundle --> wg["VPN config<br/>(WireGuard app)"]
    bundle --> tak["TAK data package<br/>(ATAK / iTAK / WinTAK)"]
    bundle --> mx["Matrix server and login<br/>(Element or another Matrix app)"]
    bundle --> ca["Waveshift certificate<br/>(so the device trusts the servers)"]

4. Being in more than one Egress Server

A person in two Egress Servers keeps both bundles on their device. They choose which Egress Server they are on by turning on that Egress Server's VPN tunnel; that Egress Server's TAK and Matrix then connect, and the other Egress Server's show as offline until they switch. Phones only run one VPN tunnel at a time, so this is how they already behave.

flowchart LR
    subgraph phone["Alice's phone"]
        direction TB
        wgA["VPN: Kestrel<br/>(ON)"]
        wgB["VPN: Osprey<br/>(off)"]
        takAppA["ATAK: Kestrel connection"]
        takAppB["ATAK: Osprey connection"]
        mxAppA["Matrix: Kestrel account"]
        mxAppB["Matrix: Osprey account"]
    end

    subgraph popA["Egress Server: Kestrel"]
        takA["TAK server"]
        mxA["Matrix server"]
    end

    subgraph popB["Egress Server: Osprey"]
        takB["TAK server"]
        mxB["Matrix server"]
    end

    wgA ==> popA
    takAppA ==> takA
    mxAppA ==> mxA
    wgB -.-> popB
    takAppB -.-> takB
    mxAppB -.-> mxB

Solid lines are connected; dotted lines are waiting for the user to switch tunnel.

5. Who can see whom

People only see others in the same Egress Server. Someone in two Egress Servers has a separate identity in each, so they never become a bridge between them: what Alice posts in Kestrel stays in Kestrel.

flowchart TB
    subgraph popA["Egress Server: Kestrel"]
        aliceA["Alice (Kestrel identity)"]
        carol["Carol"]
        aliceA <--> carol
    end

    subgraph popB["Egress Server: Osprey"]
        aliceB["Alice (Osprey identity)"]
        bob["Bob"]
        aliceB <--> bob
    end

    carol x--x bob

Carol and Bob cannot see or message each other. Alice can work in both, but as two separate identities.

6. Changing the team

Adding or removing a person updates every service in the Egress Server together. Removing someone takes away all of their access to that Egress Server at once, and nothing else they have.

sequenceDiagram
    actor owner as Egress Server owner
    participant console as Waveshift Console
    participant vpn as Kestrel VPN
    participant tak as Kestrel TAK
    participant mx as Kestrel Matrix

    owner->>console: Add Dave to Kestrel
    console->>vpn: Create Dave's VPN config
    console->>tak: Create Dave's TAK login and certificate
    console->>mx: Create Dave's Matrix account
    console-->>owner: Dave added, his bundle is in the console

    owner->>console: Remove Dave from Kestrel
    console->>vpn: Revoke Dave's VPN config
    console->>tak: Revoke Dave's TAK certificate
    console->>mx: Deactivate Dave's account and sign out his devices
    console-->>owner: Dave removed from Kestrel only

7. The life of an Egress Server

Egress Servers are disposable. When one is deleted, its servers and everything stored on them are deleted with it.

stateDiagram-v2
    [*] --> Building: Owner creates Egress Server
    Building --> Active: Servers and accounts ready
    Active --> Active: Team members added or removed
    Active --> ShuttingDown: Owner schedules shutdown
    ShuttingDown --> Deleted: Users warned, Egress Server deleted
    Deleted --> [*]

    note right of ShuttingDown
        Users switch to their other Egress Servers.
        Any records to keep are exported now.
    end note
    note right of Deleted
        Servers, messages, TAK data
        and VPN access are gone.
        Other Egress Servers are not affected.
    end note

8. Options

Where the servers live

Each Egress Server gets its own servers (the chosen approach) rather than sharing one central server split into groups. With a central server, someone in two groups can carry information from one to the other, and deleting an Egress Server does not delete its data.

flowchart LR
    subgraph chosen["Chosen: servers per Egress Server"]
        direction TB
        p1["Egress Server Kestrel"] --> s1["Its own TAK and Matrix"]
        p2["Egress Server Osprey"] --> s2["Its own TAK and Matrix"]
    end

    subgraph alt["Alternative: one central server"]
        direction TB
        q1["Egress Server Kestrel"] --> c["Shared TAK and Matrix<br/>(split into groups)"]
        q2["Egress Server Osprey"] --> c
    end

	Servers per Egress Server	One central server
Egress Servers fully separated	Yes	Only by group settings
Deleting an Egress Server deletes its data	Yes	Needs a separate clean-up
Cost	One small server per service per Egress Server	One server
Same behaviour for TAK and Matrix	Yes	Differs per service

Connecting to several Egress Servers

Today: one VPN config per Egress Server, switching between them. Later, possibly: one combined config that connects to all of a person's Egress Servers at once. That needs every Egress Server to use different network addresses, which the console would have to plan.

flowchart LR
    subgraph now["Now: one tunnel per Egress Server"]
        direction TB
        d1["Device"] -- "Kestrel tunnel (on)" --> n1["Kestrel"]
        d1 -. "Osprey tunnel (off)" .-> n2["Osprey"]
    end

    subgraph later["Later: one combined tunnel"]
        direction TB
        d2["Device"] -- "single tunnel" --> m1["Kestrel"]
        d2 -- "single tunnel" --> m2["Osprey"]
    end

	One tunnel per Egress Server (now)	Combined tunnel (later)
On several Egress Servers at the same time	No, switch between them	Yes
Works with today's Egress Server networks	Yes	Needs non-overlapping addresses
Joining or leaving an Egress Server	Add or remove one config	Re-import the combined config
Status	Ready to build	Needs design work