stacklok / stacklok/toolhive

Change the CLI to call the HTTP API instead of calling core code directly

Open
#1,279 0 comments 0 reactions 1 assignee View on GitHub

@lujunsan is already working on this.

Since Aug 12, 2025.

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

Description

Currently the ToolHive codebase has two distinct ways of interacting with the core code:

  1. The CLI calls the core code directly.
  2. The UI calls a REST API, which calls the core code.

Having two separate pathways leads to situations where logic implemented for the CLI but not the UI, or vice-versa. Even if this problem was solved for, there are various problems which arise including:

  1. In a model where both the UI and CLI are deployed, there is the potential to end up with race conditions due to different processes mutating the same state. In this proposed flow, it becomes much easier to reason about locking since there is a single process handling all changes to local state.
  2. Complexities around update checking.
  3. The restart problem - right now, because there is no background process, there is nothing that will automatically re-start workloads after the host (or the docker daemon) has been restarted. In this proposed flow, since there is a service definition, the API server will get started on boot and it can restart any workloads which need to be restarted.
  4. Logging - we need the same code to produce structured logs for the API case, and human-readable logs for the CLI case.
  5. The CLI cannot interact with remote instances of toolhive.

Proposed solution:

Change the CLI to call the REST API. This will look like Docker's architecture - we will have a REST API running as a background daemon (bootstrapped by systemd/launchd/Windows Services) and the CLI is simply a client of the API.

TODO: Figure out how we will package and deploy this across the different platforms we support.

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.