Network Interface Discovery

Identify which TUN interface (e.g., utun16) Tailscale is using.

New Features

• NetworkInterfaceDiscovery - Uses BSD getifaddrs API to enumerate system network interfaces
• StatusResponse.interfaceName - Convenient computed property returning the TUN interface name
• StatusResponse.interfaceInfo - Full interface details including up/running/point-to-point state

Usage

let client = TailscaleClient()
let status = try await client.status()
// Get the interface name
if let iface = status.interfaceName {
 print("Tailscale interface: \(iface)") // e.g., "utun16"
}
// Get full interface info
if let info = status.interfaceInfo {
 print("Interface \(info.name): up=\(info.isUp), running=\(info.isRunning)")
}

Testing

• 17 new unit tests for interface discovery
• 3 new integration tests validating against live daemon
• Total: 82 tests (62 active, 20 integration tests)

🤖 Generated with Claude Code

What's New

This release adds critical endpoints for monitoring and tooling use cases.

New Endpoints

• whois(address:) - Identity lookup by Tailscale IP or node key
• prefs() - Read current node preferences and configuration
• ping(ip:type:size:) - Network connectivity diagnostics with latency measurement
• metrics() - Internal Tailscale metrics in Prometheus format

CLI Commands

• tailscale-swift whois <ip> - Look up identity for a Tailscale IP
• tailscale-swift prefs - Display current node preferences
• tailscale-swift ping <ip> [-c count] [-t type] - Test connectivity
• tailscale-swift health - Display health warnings
• tailscale-swift metrics [--filter] - Show internal metrics

Improvements

• Pure Swift LocalAPI discovery - Replaced lsof shell-out with libproc APIs (~10x faster)
• Comprehensive test coverage - 66% line coverage with 62 unit tests and 17 integration tests
• Updated documentation - README with API reference and expanded quickstart

See CHANGELOG.md for full details.

Improved

Error Handling

• Added specific transport error types for better diagnostics:
  • socketNotFound(path:) - Unix socket doesn't exist
  • connectionRefused(endpoint:) - Daemon not listening
  • malformedResponse(detail:) - HTTP response parsing failed
• Added endpoint context to unexpectedStatus and decoding errors
• Added bodyPreview property on TailscaleClientError for debugging (truncates to 500 chars)
• Implemented LocalizedError protocol with recoverySuggestion for all error types
• Human-readable error descriptions with actionable guidance

CLI Exit Node Display

• Display active exit node prominently when routing through one
• Show connection quality details:
  • Connection type (direct IP:port vs DERP relay)
  • DERP relay location when applicable
  • Last WireGuard handshake time
  • Traffic statistics (rx/tx bytes with human-readable formatting)
• List available exit nodes in verbose mode

Fixed

• Transport errors now pass through specific error types instead of wrapping all errors in networkFailure

Full Changelog: v0.1.0...v0.1.1

swift-tailscale-client v0.1.0

First official release! 🎉

An unofficial Swift 6 client for the Tailscale LocalAPI. This package connects to existing tailscaled daemons to query their state and configuration—perfect for building monitoring tools, status widgets, and developer utilities.

Note: This package connects to existing Tailscale installations. If you need to embed Tailscale into your app, see Tailscale's official TailscaleKit instead.

What's Included

Core Library

• ✅ Full /localapi/v0/status endpoint with comprehensive Swift models
• ✅ TailscaleClient actor with async/await API
• ✅ Strict Swift 6 concurrency with complete Sendable conformance
• ✅ Comprehensive models: StatusResponse, NodeStatus, UserProfile, TailnetStatus, BackendState

Transport & Discovery

• ✅ Protocol-oriented transport abstraction (TailscaleTransport)
• ✅ Unix socket & TCP loopback support
• ✅ macOS LocalAPI discovery (lsof probe ~140ms → filesystem fallback ~2s)
• ✅ Automatic header injection (Tailscale-Cap, Basic Auth)

Configuration

• ✅ Environment variable overrides for all settings
• ✅ Pluggable transport for testing and custom implementations
• ✅ Flexible configuration via TailscaleClientConfiguration

Development Tools

• ✅ tailscale-swift CLI tool with status command
• ✅ Man page and comprehensive help (--help)
• ✅ Built with Swift Argument Parser

Testing & Quality

• ✅ Comprehensive test suite (unit + integration tests)
• ✅ GitHub Actions CI/CD for macOS
• ✅ Swift format with zero violations
• ✅ Mock transports for testing

Documentation

• ✅ Complete DocC documentation: https://dweekly.github.io/swift-tailscale-client/
• ✅ Comprehensive README with quickstart and examples
• ✅ Contributing guidelines and code of conduct

Quick Start

import TailscaleClient
let client = TailscaleClient()
let status = try await client.status()
print(status.selfNode?.hostName ?? "unknown")

Installation

Add to your Package.swift:

.package(url: "https://github.com/dweekly/swift-tailscale-client.git", from: "0.1.0")

What's Next?

See ROADMAP.md for planned features:

• v0.2.0: Essential monitoring (/whois, /prefs GET, /ping)
• v0.3.0: Taildrop support
• v0.4.0: Streaming & diagnostics (/watch-ipn-bus)
• v0.5.0: Configuration management (/prefs PATCH)

Platform Support

• macOS 13+
• iOS 16+
• tvOS 16+
• watchOS 9+

License

MIT © 2025 David E. Weekly

Disclaimer: This is a personal project and is NOT an official Tailscale product.

Full changelog: CHANGELOG.md