#Networking

WWKG nodes communicate directly with each other over the network. CLI data commands use the node’s QUIC endpoint.

#How nodes find each other

WWKG uses multiple discovery mechanisms so that nodes can connect without manual configuration:

• Local network — nodes on the same LAN discover each other automatically. This is how the CLI finds a local node without needing a target flag.
• Global discovery — nodes register their address so that nodes on other networks can find them.
• Direct connections — once two nodes know about each other, they establish a direct connection for the lowest possible latency.

#NAT traversal and relay servers

When a node is behind a firewall or NAT (common in home networks and corporate environments), direct connections from the outside are blocked. The --relay flag tells the server to register with public relay servers that help establish connectivity:

wwkg node serve --relay

With relay enabled:

1. Your node registers with one or more relay servers.
2. Remote nodes connect to the relay, which forwards traffic to your node.
3. Whenever possible, WWKG upgrades the relayed connection to a direct link. The relay is then no longer involved.

Relay servers never see your data in plaintext — all workspace data is end-to-end encrypted before it leaves your node.

Use --relay when your node needs to be reachable by nodes outside your local network.

#Connection methods

The CLI supports several ways to connect to a server:

#Automatic discovery (default)

wwkg graph query "SELECT * WHERE { ?s ?p ?o } LIMIT 10"

The client discovers a WWKG server on the local network automatically. No configuration required.

#Direct connection via ticket

If the server is not on the local network, use a connection ticket:

wwkg graph query "SELECT * WHERE { ?s ?p ?o }" --ticket <ticket>

Or set the WWKG_TICKET environment variable:

export WWKG_TICKET=<ticket>
wwkg graph query "SELECT * WHERE { ?s ?p ?o }"

#Known node selection

When the node is already registered locally or discoverable by ID, select it directly:

wwkg --node <node-id-or-name> graph query "SELECT * WHERE { ?s ?p ?o }"

#Installing a host

Each machine runs at most one of each role (host, gateway, custodian, worker). To install just the host daemon:

sudo wwkg install --apt --node-only

The host listens on QUIC port 4243 by default. It stores data under /var/db/wwkg/host (macOS) or /var/lib/wwkg/host (Linux).