whosthere

Themes can be set via the configuration file or at runtime using CTRL+t.

• Set theme.name to a built-in theme name.
• Set theme.name to custom to use manual color overrides (e.g., primitive_background_color, border_color, etc.).
• If theme.enabled is false, the TUI uses the terminal's default ANSI colors.
• The NO_COLOR environment variable will disable all ANSI colors.

theme:
  enabled: true
  name: cyberpunk

You can install Whosthere using various package managers depending on your operating system or build it from source using Go.

# Homebrew
brew install whosthere

# NixOS
nix profile install nixpkgs#whosthere

# Arch Linux
yay -S whosthere-bin

# Go
go install github.com/ramonvermeulen/whosthere@latest

# Build from source
git clone https://github.com/ramonvermeulen/whosthere.git
cd whosthere
make build

Whosthere is a Local Area Network (LAN) discovery tool that provides an interactive Terminal User Interface (TUI) to discover, explore, and understand devices on your network. The CLI follows a standard command structure: whosthere [global flags] <subcommand> [args].

Available subcommands include:

• version: Displays the current version of whosthere.
• daemon: Runs whosthere in daemon mode.
• scan: Performs a network scan.

Whosthere uses a YAML configuration file for persistent settings. The file is searched in this order:

1. Path specified via --config flag or WHOSTHERE_CONFIG environment variable.
2. $XDG_CONFIG_HOME/whosthere/config.yaml.
3. ~/.config/whosthere/config.yaml (default).

Example Configuration

# network_interface: eth0

all_interfaces: false

scan_interval: 20s

scan_timeout: 10s

scanners:
  mdns:
    enabled: true
  ssdp:
    enabled: true
  arp:
    enabled: true

sweeper:
  enabled: true
  interval: 5m
  timeout: 20s

port_scanner:
  timeout: 5s
  tcp: [21, 22, 23, 25, 80, 110, 135, 139, 143, 389, 443, 445, 993, 995, 1433, 1521, 3306, 3389, 5432, 5900, 8080, 8443, 9000, 9090, 9200, 9300, 10000, 27017]

splash:
  enabled: true
  delay: 1s

theme:
  enabled: true
  name: default

You can override any YAML configuration option using environment variables with the WHOSTHERE__ prefix. Nested keys are separated by double underscores (__) and are case-insensitive.

General Environment Variables

Examples

• WHOSTHERE__SPLASH__ENABLED=false (equivalent to splash.enabled: false)
• WHOSTHERE__SCAN_INTERVAL=30s (equivalent to scan_interval: 30s)
• WHOSTHERE__SCANNERS__MDNS__ENABLED=false (equivalent to scanners.mdns.enabled: false)
• WHOSTHERE__PORT_SCANNER__TCP=80,443,8080 (equivalent to port_scanner.tcp: [80, 443, 8080])
• WHOSTHERE__THEME__NAME=cyberpunk (equivalent to theme.name: cyberpunk)

The App manages a discovery.Engine which is responsible for scanning the network.

Interface Switching

When a user switches network interfaces, the application performs a coordinated swap:

1. It acquires a write lock (engineMu) to prevent concurrent device updates.
2. It cancels the existing engine's context (engineCancel).
3. It stops the old engine.
4. It increments an engineGen (generation counter) to invalidate any pending events from the old engine.
5. It builds and starts a new engine for the selected interface.

Event Processing

The handleEngineEvents goroutine listens to the engine's event channel. It uses the generation counter to ensure that if an interface switch occurs, events from the 'old' engine are discarded and do not pollute the state with stale device data.

Whosthere requires an external copy tool to support clipboard actions (y and Y in TUI). Ensure the following tools are installed for your OS:

• Darwin (macOS): pbcopy
• Windows: clip.exe
• Linux/FreeBSD/NetBSD/OpenBSD/Dragonfly:
  • X11: xsel or xclip
  • Wayland: wl-copy

When running in daemon mode, Whosthere exposes a simple HTTP API for accessing discovered device data.

| Method | Endpoint | Description |
| ------ | -------- | ----------- |
| GET | `/devices` | Get list of all discovered devices |
| GET | `/device/{ip}` | Get details of a specific device |
| GET | `/health` | Health check |

Use the following keyboard shortcuts to navigate and interact with the TUI:

To run Whosthere in the background as a daemon and expose its discovery data via an HTTP API, use the daemon command. You can specify the listening port with --port.

whosthere daemon --port=8080

To launch the interactive Terminal User Interface (TUI) for exploring your LAN, run the command without arguments.

whosthere