Auto-detect Docker Desktop socket on Linux#5122
Merged
Conversation
Docker Desktop on Linux exposes its Engine socket at $HOME/.docker/desktop/docker.sock and registers a desktop-linux Docker context pointing there. ToolHive runtime auto-detection only probed /var/run/docker.sock and macOS-specific paths, so on a Linux host with only Docker Desktop installed IsAvailable returned false and CheckRuntimeAvailable failed with "no container runtime available" -- even though docker ps in the same shell worked fine via the active context. Add the Linux Docker Desktop socket to the discovery list so auto-detection finds it without requiring TOOLHIVE_DOCKER_SOCKET. Wrap the system socket path in an unexported package variable so tests can redirect the system probe to a sandbox path.
Cover three cases for Docker socket auto-detection: - discovery of the new Docker Desktop on Linux socket at $HOME/.docker/desktop/docker.sock when no system socket is present; - TOOLHIVE_DOCKER_SOCKET env override wins over filesystem discovery; - ErrRuntimeNotFound when no socket is reachable. The tests redirect the system socket probe via the unexported systemDockerSocketPath variable so they stay hermetic on machines that already have /var/run/docker.sock.
Match the documented runtime discovery order to the code by adding the Linux Docker Desktop socket path next to the existing macOS-specific entries in docs/arch/01-deployment-modes.md.
samuv
requested review from
ChrisJBurns,
JAORMX,
amirejaz,
blkt,
jhrozek,
rdimitrov and
yrobla
as code owners
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #5122 +/- ##
==========================================
+ Coverage 67.12% 67.15% +0.03%
==========================================
Files 597 597
Lines 60170 60177 +7
==========================================
+ Hits 40390 40414 +24
+ Misses 16706 16686 -20
- Partials 3074 3077 +3 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
JAORMX
approved these changes
Apr 30, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
/var/run/docker.sock),thvfails to start withno container runtime available, even thoughdocker/docker pswork fine. Docker Desktop on Linux runs Engine inside a VM and exposes its socket at~/.docker/desktop/docker.sockand registers adesktop-linuxDocker CLI context pointing there.findDockerSocketonly probed/var/run/docker.sockplus macOS-specific paths (Docker Desktop on macOS, Rancher Desktop, OrbStack), so the Linux Docker Desktop socket was never discovered. The Docker CLI works because it honors~/.docker/config.json/~/.docker/contexts/meta; ToolHive's Go discovery does not consult contexts, it stats a fixed list.TOOLHIVE_DOCKER_SOCKETmanually.Fixes #5120
Type of change
Test plan
go test ./pkg/container/docker/sdk/... ./pkg/container/...)task lint-fix— 0 issues)pkg/container/docker/sdk/client_unix_test.go:TestFindDockerSocket_DockerDesktopOnLinux— hermetic test that creates a fake~/.docker/desktop/docker.sockand assertsfindDockerSocketreturns it.TestFindPlatformContainerSocket_DockerEnvOverrideWins—TOOLHIVE_DOCKER_SOCKETtakes precedence over filesystem discovery.TestFindPlatformContainerSocket_NotFound—ErrRuntimeNotFoundis still returned when no socket is reachable.thv version/thv listwork without the env override.Changes
pkg/container/docker/sdk/factory.goDockerDesktopLinuxSocketPathconstant for~/.docker/desktop/docker.sock.pkg/container/docker/sdk/client_unix.gofindDockerSocket; wrap the system socket path in unexportedsystemDockerSocketPathso tests can redirect it.pkg/container/docker/sdk/client_unix_test.godocs/arch/01-deployment-modes.mdDoes this introduce a user-facing change?
Yes — Linux users running only Docker Desktop now get working
thvruntime auto-detection with no extra configuration. Hosts that already have/var/run/docker.sock(system Docker Engine) see no change; the system socket is still probed first and wins.Implementation plan
Approved implementation plan
DockerDesktopLinuxSocketPath = ".docker/desktop/docker.sock"next to the other socket-path constants inpkg/container/docker/sdk/factory.go.findDockerSocketinpkg/container/docker/sdk/client_unix.goto probe$HOME/.docker/desktop/docker.sock, ordered after the macOS Docker Desktop check and before the Rancher / OrbStack fallbacks. Keep/var/run/docker.sockfirst so a system Docker Engine still wins.systemDockerSocketPathpackage variable defaulted toDockerSocketPathso tests can redirect the system probe to a sandbox path without affecting production.pkg/container/docker/sdk/client_unix_test.gocovering: discovery of the new Linux Docker Desktop socket, env override (TOOLHIVE_DOCKER_SOCKET) precedence, andErrRuntimeNotFoundwhen nothing is reachable.docs/arch/01-deployment-modes.mdso the documented discovery order matches the code.Out of scope: parsing
~/.docker/config.json/~/.docker/contexts/metato honor arbitrary Docker contexts. That generalizes beyond the well-known Docker Desktop path but is heavier; leaving it as a follow-up if a custom-context case shows up.Special notes for reviewers
systemDockerSocketPathvariable is unexported and exists purely as a test seam — its production value isDockerSocketPathand never changes at runtime.