Summary
A client cannot find a daemon on the network. The user must know the
endpoint URL and type it. This is not easy.
I propose we add Bonjour to the daemon. With Bonjour, the daemon
sends its name and address on the local network. A client app can then
find the daemon and show its endpoint to the user.
I am building an iOS app (via Uno Platform) for Netclaw. It is a separate product in a
separate repo. That app is the first client for this feature, and it
is the test for the design.
Current state
- The daemon does not send announcements on the network.
- The daemon binds to
127.0.0.1:5199 by default
(Netclaw.Daemon/Program.cs).
DaemonConfig.ExposureMode has these values: local,
reverse-proxy, tailscale-serve, tailscale-funnel, and
cloudflare-tunnel.
- The pairing flow controls trust. Discovery only helps a client find
the endpoint. Discovery must not change the pairing flow.
Design
- The daemon uses Bonjour to send the service
_netclaw._tcp.local.
- The daemon sends the service only when it is available from other
machines. The daemon must not send the service in the local
exposure mode.
- The instance name is the service name of the daemon. If there is no
service name, use the host name.
- The TXT record has only these keys:
version — the protocol version
tls — 0 or 1
path — the base path prefix, if set
Do not add other keys. Do not add device names. Do not add token
data. The version key lets us change the record format for future
clients.
- Configuration: add the boolean
AdvertiseOnLan to DaemonConfig.
The default value is off. Update netclaw-config.v1.schema.json in
the same PR (schema sync rule).
- Doctor: show if the advertisement is active. Show a warning when
AdvertiseOnLan is true but the exposure mode stops the
advertisement.
Security requirements
- The advertisement is off by default. The advertisement must not be
active in the local exposure mode.
- A client that finds a daemon is not trusted. The client must
complete the one-time pairing code exchange first.
- The TXT record has only the three keys given above.
Acceptance criteria
Follow-up work (separate issues)
- Discovery on more platforms after the iOS app shows that the flow
is good.
- Discovery through Tailscale. Multicast does not go across the
tailnet.
Out of scope
- All client-side work. The iOS app is a separate product and repo,
and its browsing feature is tracked there.
- A custom UDP beacon protocol.
Summary
A client cannot find a daemon on the network. The user must know the
endpoint URL and type it. This is not easy.
I propose we add Bonjour to the daemon. With Bonjour, the daemon
sends its name and address on the local network. A client app can then
find the daemon and show its endpoint to the user.
I am building an iOS app (via Uno Platform) for Netclaw. It is a separate product in a
separate repo. That app is the first client for this feature, and it
is the test for the design.
Current state
127.0.0.1:5199by default(
Netclaw.Daemon/Program.cs).DaemonConfig.ExposureModehas these values:local,reverse-proxy,tailscale-serve,tailscale-funnel, andcloudflare-tunnel.the endpoint. Discovery must not change the pairing flow.
Design
_netclaw._tcp.local.machines. The daemon must not send the service in the
localexposure mode.
service name, use the host name.
version— the protocol versiontls— 0 or 1path— the base path prefix, if setDo not add other keys. Do not add device names. Do not add token
data. The
versionkey lets us change the record format for futureclients.
AdvertiseOnLantoDaemonConfig.The default value is off. Update
netclaw-config.v1.schema.jsoninthe same PR (schema sync rule).
AdvertiseOnLanis true but the exposure mode stops theadvertisement.
Security requirements
active in the
localexposure mode.complete the one-time pairing code exchange first.
Acceptance criteria
_netclaw._tcpwhenAdvertiseOnLanis trueand the bind address is not loopback. The command
dns-sd -B _netclaw._tcpon a different machine on the samenetwork shows the service.
version,tls, andpath.localmode. The daemondoes not send the service when
AdvertiseOnLanis false. Unittests make sure of this.
netclaw doctorshows the advertisementstate.
documentation as the discovery contract. External clients, such
as my iOS app, can then code against the contract.
Follow-up work (separate issues)
is good.
tailnet.
Out of scope
and its browsing feature is tracked there.