stacklok / stacklok/toolhive

Support configuring container engine socket path via config file

Open
#4,612 1 comment 0 reactions 1 assignee View on GitHub

@kantord is already working on this.

Since Apr 9, 2026.

cli enhancement
Dominant language
Go
Stars
2.2k
Forks
300
Avg merge
1d 15h
Merged PRs (30d)
184

Description

Current Behavior

Socket paths can only be overridden via environment variables:

  • TOOLHIVE_DOCKER_SOCKET
  • TOOLHIVE_PODMAN_SOCKET
  • TOOLHIVE_COLIMA_SOCKET

These are checked in pkg/container/docker/sdk/client_unix.go before falling back to auto-detection of standard socket locations. There is no way to persist this configuration in the ToolHive config file (~/.config/toolhive/config.yaml), meaning users with non-standard socket paths must set environment variables in every shell session or wrapper script.

Proposed Change

Add socket path fields to the Config struct in pkg/config/config.go, allowing users to configure them once via thv config or by editing the YAML file directly:

container_runtime:
  docker_socket: /run/user/1000/docker.sock
  podman_socket: /run/user/1000/podman/podman.sock
  colima_socket: /home/user/.colima/custom/docker.sock

Socket resolution in findPlatformContainerSocket would check sources in this order, preserving existing precedence:

  1. Environment variable (existing)
  2. Config file (new)
  3. Auto-detection of standard paths (existing)

Motivation

Configuring environment variables across GUI and CLI apps can be a bad experience, because there are various ways env variables can be set up, and not all of them are accessible by both GUI and CLI processes - it can actually even depend on how the process is launched.

Misconfiguration is hard to spot, but can lead to confusing, unexpected experiences. This is not user friendly, because users should not need to have a deep understanding of how their operating system handles environment variables across different ways of launching apps just to be able to use ToolHive.

See [this Discord thread for a concrete user report that illustrates the problem.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.