Platform-Specifics
Relevant source files
The following files were used as context for generating this wiki page:
The Tusk Drift CLI is designed to run on multiple operating systems, including Linux, macOS, and Windows. To provide a consistent user experience, the CLI abstracts away platform-specific details, particularly in areas of inter-process communication (IPC), process management, and dependency installation. This is achieved through the use of Go's build constraints, which compile different code for different target operating systems.
This document outlines the key areas where the implementation diverges between Unix-like systems (Linux, macOS) and Windows, providing insight into the underlying mechanisms that enable cross-platform compatibility.
Installation and Dependencies
The installation process and required dependencies vary by platform.
| Platform | Dependencies | Installation Method | Notes |
|---|---|---|---|
| Linux | bubblewrap, socat | curl -fsSL https://cli.usetusk.ai/install.sh | sh | Dependencies are required for replay sandboxing and network isolation. |
| macOS | None | curl -fsSL https://cli.usetusk.ai/install.sh | sh | Sandboxing dependencies are not required. |
| Windows | None | Manual download or WSL | The recommended approach is to use Windows Subsystem for Linux (WSL) and follow the Linux installation. Native Windows support requires specific configuration for TCP communication. |
Sources: README.md:92-98, README.md:105-125
Inter-Process Communication (IPC)
The Tusk Drift CLI runner communicates with the service under test to mock outbound I/O during replays. The method of communication is a primary point of divergence between platforms. The tusk init onboarding wizard explicitly asks if the service will run with Docker to determine which communication method to configure.
Sources: internal/tui/onboard/steps.go:108-114
Unix Sockets (Linux/macOS)
On Unix-like systems, the runner creates a Unix domain socket for IPC. This is the default and preferred method for local, non-containerized test runs.
The diagram below shows the IPC listener setup on Unix systems.
The Listen function in service_unix.go implements this by calling net.Listen with the "unix" network type.
Sources: internal/runner/service_unix.go:12-15
TCP Sockets (Windows/Docker)
On Windows, or when running tests within Docker containers on any platform, the runner uses TCP sockets for communication. This is necessary because Unix sockets are not available on native Windows and are more complex to handle across Docker network boundaries.
The diagram below shows the IPC listener setup on Windows or with Docker.
The Listen function in service_windows.go uses net.Listen with the "tcp" network type, binding to a port on the loopback interface. The tusk init wizard guides users to create a docker-compose.tusk-override.yml file, which may include extra_hosts configuration on Linux to ensure the container can reach the host.
Sources: internal/runner/service_windows.go:13-16, internal/tui/onboard/view.go:114-121
Process Management
The CLI needs to manage child processes, such as starting the user's service or killing processes on a specific port.
Process Sandboxing
On Unix systems, the AI setup agent can use fence to sandbox commands, providing network isolation. This feature relies on bubblewrap and is enabled by default unless explicitly disabled. The process manager for Windows does not include this sandboxing capability.
Sources: internal/agent/tools/process_unix.go, internal/agent/tools/process_windows.go
Killing Processes by Port
During the AI setup flow, the agent may need to kill a process that is occupying a required port. The implementation for this is platform-specific. On Unix-like systems, it uses a shell command combining lsof and kill.
The sequence diagram below illustrates this process on a Unix system.
The killProcessOnPort function in agent.go demonstrates this Unix-specific implementation.
// internal/agent/agent.go:1025-1028
func killProcessOnPort(port int) error {
cmd := exec.Command("sh", "-c", fmt.Sprintf("lsof -ti:%d | xargs kill -9 2>/dev/null || true", port)) //nolint:gosec // Port is an integer, safe to interpolate
return cmd.Run()
}
Sources: internal/agent/agent.go:1025-1028
Release and Distribution
The project uses GoReleaser to automate the build and release process for multiple platforms and architectures. This ensures that native binaries are available for a wide range of systems.
The following platforms and architectures are targeted for each release:
| Platform | Architectures |
|---|---|
| Linux | amd64, arm64 |
| macOS (darwin) | amd64, arm64 |
| Windows | amd64, arm64 |
This multi-platform build strategy is defined in the project's CI configuration and documented in CONTRIBUTING.md.
Sources: CONTRIBUTING.md:143-147