stacklok / stacklok/toolhive

thv llm: support the OAuth device flow for headless and remote SSH boxes

Open
#6,357 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

As a developer working on a remote or headless box
I want to authenticate to the LLM gateway with the OAuth device flow
So that I can log in without a local browser that can call back to localhost.

Why

thv llm token completes its OIDC login by having the browser redirect to a localhost callback. On a headless Linux box or over SSH there is no browser on the machine, so the flow cannot complete. The only route today is SSH localhost port forwarding, which is not discoverable and not automatable.

Raised twice last week during dogfooding:

  • Headless box thread — "when running on a headless box, it expects that my browser can call back to localhost. But I'm not running a browser there. This whole codepath keeps giving me errors and is super frustrating… We should support the OAuth device flow for situations like this." The reporter ultimately abandoned thv llm and switched to a static API key.
  • thv-dependency thread — the same friction framed as an argument for not requiring thv at all.

Notes

  • Related but distinct: the same thread hit the secrets-provider requirement (no desktop keyring on a headless box, password prompt on every reboot). Worth a separate issue.
  • thv llm token was built to never launch a browser flow in non-interactive mode (#5028); device flow gives that mode a way to actually succeed rather than just failing cleanly.
  • thv llm setup --lazy (#5386) defers login for unattended provisioning, so device flow is the natural completion of that path.

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.

Research direction

Start at the thv llm token entry point and trace its current OIDC localhost-callback flow, then review the non-interactive behavior described in #5028 and the deferred login path from #5386. Done means headless or SSH users can complete authentication through the OAuth device flow without a local browser callback; the issue does not name specific files or tests.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
authentication, cli
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.