Skip to main content

Module: connectors

External accounts the node holds credentials for — GitHub, Google, an API-key provider — surfaced as a row of tiles above the ask bar on the home page. One connector owns three things: how you connect it, the credential once you have (held server-side, encrypted, never handed to the browser), and the agent tools it unlocks.

Status: GitHub + Google implemented. Backend in backend/modules/connectors/, contract in backend/sdk/types.py, frontend in packages/ui/src/home/ + packages/core/src/connectors/api.ts.

Why this is not the games sign-in​

The games module has had "Sign in with GitHub/Google" for a while, and it cannot be reused here — it is identity-only by construction:

  • its OAuth client runs in a separate process (backend/games_server/, deployed to Fly), which holds the client secrets;
  • it asks for minimal scopes (read:user, email profile) with access_type=online;
  • _finish_github / _finish_google take only the profile dict and discard the provider access token, keeping just enough to mint the game server's own player JWT. The accounts table has no token column.

Nothing in that path can search GitHub. Connectors are a separate, token-retaining OAuth client that runs on this node — which is also why the credential can stay local.

The contract​

A connector is contributed through the backend plugin SDK, so a built-in module and a third-party backend plugin register identically (see backend-plugin-sdk):

host.add_connector(Connector(
id="github", # MUST equal the agent-tool namespace — see below
label="GitHub",
kind="oauth", # oauth | api-key | custom
icon="github", # slug the frontend resolves; unknown -> letter avatar
blurb="Search code and repositories…", # one line; doubles as the agent group blurb
scopes=[ConnectorScope(id="repo", label="Read your repositories", description="…")],
guide=guide_loader("github"), # SKILL.md-style agent guide
status=_status, begin=_begin, poll=_poll, disconnect=_disconnect,
))

Connector.id must equal the prefix of the agent tools it enables (github → github.searchCode). The orchestrator derives a tool's group from its name prefix, so a mismatch silently splits a connector's tools off from its blurb and guide. A test locks the invariant (test_connectors.py).

One machine, three kinds​

begin → optionally submit → optionally poll. A single step shape covers every kind, which is the point — custom is just a form step that may return another form step, so Clubhouse's phone → SMS → connected flow needs no new concepts.

kindbegin returnsthen
oauth (device){step:'device', user_code, verification_uri, interval}poll until {connected}
oauth (redirect){step:'redirect', authorize_url}poll until {connected}
api-key{step:'form', fields:[…]}submit → {connected}
custom{step:'form', fields:[…]}submit → another form step → {connected}

Routes​

Mounted at /api/connectors:

RoutePurpose
GET /Every connector + live status — the home tile row
POST /{id}/connectStart a flow; returns the first step
POST /{id}/submitAnswer a form step
POST /{id}/pollCheck an in-flight flow ({pending: true} until done)
DELETE /{id}Drop the credential (idempotent)
GET /{id}/callbackA provider's redirect target

None of these ever return a token. The browser learns that an account is connected, its display name, and which scopes were granted.

Credential custody​

Credentials live in the shared secrets store (backend/modules/database/secrets_store.py) as one Fernet-encrypted record per connector under connector:<id>, holding access_token, refresh_token, expires_at, scopes, and a display-only account.

What the encryption is and isn't worth — stated plainly. The master key lives on the same machine as the database, so this is not a defense against code running as you: anything that can read the DB can read the key. What it does defend is the realistic accident — the data dir being copied somewhere it shouldn't (a cloud-synced folder, a backup, a screen share). That is exactly why the key is kept out of $HORRIBLE_DATA_DIR: co-locating it with the database it decrypts would defeat the only threat the design covers.

Key resolution: SECRETS_MASTER_KEY → SECRETS_KEY_PATH → ~/.horrible/secrets.key (generated once, owner-only). SECRETS_KEY_PATH exists so tests and multi-node dev setups can isolate the key the way they isolate the data dir.

A record that exists but won't decrypt raises SecretDecryptError rather than reading as absent, and surfaces as ConnectorStatus.error — "connected but broken" is a different thing from "never connected", and collapsing them makes a rotated key look like an unconfigured integration.

Client credentials​

A client id is public by design, so it may be a setting or a shipped default. A client secret must never be a setting — GET /api/settings returns the whole bag to the browser (see settings). Secrets come from the environment or the secrets store only.

backend/modules/connectors/config.py owns this contract for every OAuth connector, so a provider never re-implements it:

Client idClient secret
Resolution<PROVIDER>_CLIENT_ID → connectors.<id>.clientId setting<PROVIDER>_CLIENT_SECRET → secrets.db under <id>_client_secret
Sent to the browseryes (it's in every authorize URL)never — not as a value, not as a form prefill
Reported in /api/connectors—only as the boolean configured

Configuring a client from the UI​

An unconfigured connector returns a form step rather than an {error}. An error string tells you what you'd have to go and do in a terminal; a form lets you do it where you are. Submitting it persists the credentials and then chains straight into the OAuth step — you fill in the fields and land on the consent screen, rather than having to press Connect a second time.

  • configurable / configured on ConnectorModel drive the tile: an unconfigured connector offers Set up, a connected one also offers Reconfigure (rotate a secret, point at a different project). Reconfigure is POST /connectors/<id>/connect with {"options": {"reconfigure": true}} — no new route; begin already receives options.
  • The environment always wins. A field pinned by an env var renders with a note saying so and its submitted value is discarded rather than stored — persisting a setting that is never read would be a lie the UI then displays back as if in effect.
  • A blank secret means "leave it alone", not "clear it". The form can't prefill a secret, so blank cannot be a deliberate erasure — and treating it as one would break the connector every time you edited only the client id.

Adding a connector to this: give it a configured callable (Connector.configured) and a submit that calls config.apply_config.

GitHub​

Device flow, because GitHub OAuth Apps don't support PKCE — an authorization-code flow would force shipping a client secret in an app that runs on the user's machine, which is not a secret. The device flow needs no secret and no redirect URI, so it also works headless and under the desktop shell unchanged.

Scopes: read:user (identify the account), repo (search code, read files, list issues — private repos included) and gist (for notebook publishing). GitHub has no read-only repo scope for OAuth Apps, so the grant also permits writes; the agent still routes writes through the permission gate.

gist was added after the first sign-ins, and a token only carries the scopes it was issued with. github.granted_scopes() reads them off the stored credential rather than assuming SCOPES, so a feature that needs a newer scope can say reconnect GitHub instead of relaying GitHub's bare 404. The HTTP call itself lives in github_api.request, shared by the agent tools and the publisher; its error dicts carry a status so a caller can tell "not found" (create it) from "forbidden". Configure it in the app (the tile's Set up form), or with GITHUB_CLIENT_ID / the connectors.github.clientId setting. No client secret is asked for, because the device flow doesn't use one.

GitHub OAuth App user tokens don't expire by default, so ensure_fresh is a no-op for this connector.

Repo-viewer routes​

github_routes.py backs the GitHub viewer pane. It lives beside the connector rather than in a backend/modules/github/ of its own, mirroring google_routes.py: the token is reached through github_tools._request, and a separate module would have to import another module's private helpers.

Route (under /api/connectors/github)Purpose
GET /reposthe connected user's repositories
GET /search/repos?q=repository search
GET /repos/{owner}/{repo}metadata, incl. default_branch
GET /repos/{owner}/{repo}/branchesbranch names
GET /repos/{owner}/{repo}/tree?ref=the whole tree in one request
GET /repos/{owner}/{repo}/contents?path=&ref=one directory (lazy fallback)
GET /repos/{owner}/{repo}/file?path=&ref=one file's text; backs the github: buffer scheme
GET /repos/{owner}/{repo}/readme?ref=the README, 404 when there isn't one

All of them cache (60 s for the repo list, 300 s for refs/trees/files, ?fresh=1 to bypass) because GitHub allows 5000 requests/hour and browsing is read-heavy and repetitive. Errors keep github_tools' error-as-value convention internally and become HTTP codes at the boundary: 409 for "not connected" (yours to fix), 502 for anything upstream.

Google​

Loopback authorization-code + PKCE, not the device flow: Google's limited-input device flow only permits a small allowlist of scopes (email/profile/openid + YouTube), and drive.readonly isn't among them. Register the client as a Desktop app — Google treats that secret as non-confidential and wildcards the loopback port, so the redirect URI doesn't have to track our dev port.

Scope: drive.readonly only. The account is labelled from Drive's own about.get, which reports the signed-in user under that same scope — so no extra openid/email scope is needed just to show who's connected.

Configure it in the app (the tile's Set up form), or with GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET, or the connectors.google.clientId setting plus a google_client_secret secret (never a setting — see above).

Publish your consent screen to "In Production"

This is the single setting that decides whether you configure Google once or re-authorize every week.

An app whose consent screen is in Testing has all its refresh tokens expire after 7 days. Publishing removes that — and you can publish without verification: you get an "unverified app" interstitial and a 100-user cap, neither of which matters for a personal node.

Verification plus the annual third-party CASA assessment only become necessary to ship drive.readonly (a restricted scope) publicly to strangers — which is exactly why v1 is bring-your-own-client. With your own project the data never leaves your machine and CASA doesn't apply.

A credential that comes back without a refresh token is reported as a broken connection rather than a working one, because it would otherwise stop working an hour later with no explanation.

google tool group: driveSearch, driveRead, and syncDrive (side-effecting — it writes into a library, so it goes through the permission gate).

Drive as a browsable root​

Beyond the sync, Drive mounts into the ordinary file tree: connecting Google makes a "Google Drive" root appear in Explorer's Files section, folders expand lazily, and files open as read-only editor buffers. backend/modules/connectors/providers/drive_fs.py registers a gdrive: provider with the files module's virtual-root seam — see file explorer → Virtual roots for the mechanism, and note the path is a file id, not a name path, because Drive is an id graph.

Drive → library sync​

POST /api/connectors/google/sync ({library?, full?}) queues a background task that walks the Drive, extracts text, and files each document into a library as a note source — so Drive content becomes semantically searchable next to everything else. GET /api/connectors/google/sync reports whether a library has ever synced and how many files it tracks. The agent can trigger the same thing with google.syncDrive.

TypeHandling
Google Docexported as text/plain
PDFparsed with pypdf — chosen over PyMuPDF, which is AGPL-3.0 and would make a parser choice into a licensing one
.txt / .md / .csv / JSON / HTMLdownloaded
Sheets, Slides, imagesskipped — flattening a spreadsheet to text embeds badly

Incremental by default. The first run does a paginated full crawl and records a change token (taken before the crawl, so edits made during it aren't missed); later runs read only Drive's changes feed. Deleted and trashed files are removed from the library, so it doesn't fill up with documents that no longer exist.

One Drive file maps to one source. A google_drive_files table in app.db maps file → source, so a re-sync replaces rather than duplicating, and an unchanged file is skipped without being re-fetched. Sync state (google_drive_sync) is per-library and lives in app.db rather than settings — a page token is machine state, not a user preference.

A file that can't be read (a scanned PDF with no text layer, a password-protected one) is logged and skipped, never filed as an empty source: a blank source is worse than a missing one, because it looks like a successful sync.

This module descends from a backend/modules/integrations/google_sync.py that was deleted with the broken OAuth it depended on. It differs in four ways, each of which was a known gap called out in the original's own comments: PDFs were skipped, there was no pagination or sync state (only the 20 most recent files), the library was hardcoded, and it re-filed a duplicate source on every run.

Hugging Face​

Device flow, like GitHub — but for a different reason. Hugging Face supports public OAuth apps, created without a client secret, whose device endpoint authenticates on the client id alone. Same payoff: no secret to ship, no redirect URI to register, works headless and under the desktop shell unchanged.

Create the app from Settings → Connected Apps → Developer Applications → Create App (/settings/connected-applications), choosing no client secret, with the profile, read-repos and inference-api scopes enabled.

note

The Hub's docs deep-link to /settings/applications/new, but every HF settings page is auth-gated: logged out, it serves a login form rather than the app, so it reads as a broken link. Give the navigation path, not the URL — that's what the setup form's help text now does.

Configure it in the app (the tile's Set up form), or with HUGGINGFACE_CLIENT_ID / the connectors.huggingface.clientId setting. An app missing one of the scopes fails at POST /oauth/device with invalid_scope; that message is surfaced verbatim, because the fix is in the user's app settings.

Scopes are deliberately all read-shaped: profile (name the account), read-repos (read models and datasets, private ones included), inference-api (run inference as the user, billed to their account). The Hub also offers write-repos and manage-repos — this connector asks for neither, so a confused agent cannot delete a model. test_scopes_are_read_only is the guard on that.

The one structural difference from GitHub: these tokens expire. GitHub OAuth App user tokens live forever, so github.py has no refresher; Hugging Face issues hf_oauth_* access tokens that lapse (8h by default) alongside a refresh token. So huggingface.py implements _refresh and token() goes through ensure_fresh with it — without that the connection would quietly stop working part-way through a session. The refresh presents the client id and no secret, as a public app must.

Public repos need no connection​

Every Hub read (searchModels, searchDatasets, repoInfo, readFile, and the hub_get / read_text helpers behind the Discover pane) sends a token only when one is stored, and otherwise goes out anonymously. The Hub serves all public repos that way. A connection adds private repos, gated repos you've accepted, and a higher rate limit. Only listRepos (it needs whoami) and the write tools still answer "isn't connected". An anonymous 401 is reported as "isn't public" (private or missing), not as a rejected token, because no token was sent. GitHub has the same split: github_api.public_get reads anonymously for browsing, while request (agent tools and publishing) still requires the token.

Models and datasets are separate namespaces​

Every repo-taking tool has a type (model | dataset, default model), because squad the dataset and a model of the same name are different repos. Getting it wrong reads as a 404 for something that plainly exists — which is why the guide leads with it.

huggingface.readFile bypasses /api entirely: file content lives on the resolve CDN path, not the JSON API. It streams and caps at 100 KB so a multi-gigabyte weights file can't be pulled into memory before we notice it isn't text, and refuses binaries outright rather than handing the model a page of replacement characters.

Gated repos (Llama, Gemma, …) need the user to accept a licence on the Hub before any token can read them. repoInfo reports gated, and a read returns a "gated behind a licence" error — not something the agent can fix, and the guide says to stop rather than retry.

A browser for the human, over the same helpers​

huggingface_routes.py puts those four capabilities on HTTP for the Lab's Hugging Face pane. It lives beside the connector rather than in a module of its own, for the same reason as github_routes.py and google_routes.py: the token is held by huggingface.py and reached through huggingface_tools._request, and a separate module would have to import another module's private helpers.

MethodPathPurpose
GET/api/connectors/huggingface/searchq, type, task, sort — Hub search
GET/api/connectors/huggingface/minethe connected account's own repos
GET/api/connectors/huggingface/repometadata + file list for one repo
GET/api/connectors/huggingface/fileone text file (README, config.json, card)

The routes call _search / _list_repos / _repo_info / _read_file directly, so "find me a dataset" and "show me a dataset" are one implementation seen from two ends. Everything the agent is protected from, the pane inherits for free: the 100 KB cap, the binary refusal, the type split.

Three things differ because the caller is a browser, not an agent loop:

  • Errors become status codes. huggingface_tools returns errors as values because an agent reads the message and decides what to do next; a fetch cannot. _check maps "isn't connected" to 409 and everything else to 502 — the pane offers a connect prompt for the first and a retry for the second, so collapsing them would produce the wrong prompt, not just the wrong number.
  • repo is a query parameter, not a path segment. A Hub id is owner/name; as a path it needs escaping at every call site, and one caller forgetting is a 404 that looks like a missing repo.
  • Short-TTL caching (60s searches, 300s repos/files, 200 entries), because browsing is repetitive in a way an agent turn is not. Failures are never cached — _check raises before the store — or a "not connected" banner would outlive the connection.
gated is three-state

true / "auto" / "manual" all mean a licence must be accepted; false means open; null means the Hub didn't say. The pane renders a chip only for the first group. Coercing a missing value to false would tell the user a repo is open on no evidence.

X, LinkedIn and YouTube​

Three connectors that unlock no agent tools. Their only caller is Scrive's outbox runner, which sends what a person approved (see Scrive: the outbox). Every one is bring-your-own-app, and the configure form names the redirect URL to register: http://127.0.0.1:<backend port>/api/connectors/<id>/callback, built from the pinned port (oauth.redirect_uri), because X and LinkedIn match it exactly.

XLinkedInYouTube
Fileproviders/x.pyproviders/linkedin.pyproviders/youtube.py
Flowcode + PKCE, public client (Native App: no secret)code + client secret (no PKCE)the Google client (same Cloud project), its own consent
Scopestweet.read tweet.write users.read media.write offline.accessopenid profile w_member_socialyoutube.upload youtube.readonly
Token life2 h; refresh token rotates on every use (kept by ensure_fresh)~60 days; usually no refresh. The tile counts the days down and turns into an error a week out1 h; refresh token
Env pinsX_CLIENT_IDLINKEDIN_CLIENT_ID, LINKEDIN_CLIENT_SECRETGOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET
  • YouTube is a separate grant on purpose. Connecting Drive must not silently grant the right to publish videos, and disconnecting YouTube must not cut off Drive. The credential is stored under youtube; only the client id/secret are shared.
  • social_http.py is the one HTTP helper the three share. Failures are SendErrors that say whether retrying can help: network, 5xx and 429 (with Retry-After) are transient, 401 means reconnect, and other 4xx carry the platform's own message.
  • The tile marks are monochrome currentColor glyphs, like GitHub's.

None of the live endpoints have been exercised from this repository; the tests drive the real request code against an httpx.MockTransport of each API.

dev.to and Hashnode​

Two api-key connectors for the same outbox, which cross-posts a page's whole article to them (Scrive: cross-posting). They also unlock no agent tools.

dev.toHashnode
Fileproviders/devto.pyproviders/hashnode.py
CredentialA personal API key (Settings → Extensions)A personal access token (Account settings → Developer), and a publication
Sent asapi-key: <key> header, REST POST /api/articlesAuthorization: <token> — bare, no Bearer — GraphQL at gql.hashnode.com
Checked on connectGET /api/users/me; a key that fails is not keptme { publications }; with several, the form's publication host picks one, and its id is stored with the token
  • A blank secret on a reconfigure keeps the stored one (the form cannot prefill a secret). For Hashnode, a new publication host with a blank token re-chooses the publication with the stored token.
  • Hashnode reports errors inside a 200 response. hashnode.graphql raises them as SendErrors; an UNAUTHENTICATED or FORBIDDEN code is treated like a 401.

Agent tools + guides​

Connector tools are backend AgentTools (backend/sdk), not frontend-declared ones: the token is held server-side and the tools must work with no tab attached — a cron run, the dash REPL, agent.ask_peer. See agent-tools.

github group: searchCode, searchRepos, listRepos, readFile, listIssues. google group: driveSearch, driveRead, syncDrive. huggingface group: searchModels, searchDatasets, listRepos, repoInfo, readFile.

Each connector ships a guide — a SKILL.md-style markdown file in backend/modules/connectors/guides/<id>.md, disclosed progressively so it costs nothing on turns that never touch the connector. A guide carries what a tool description can't: search-qualifier syntax, which argument combinations are useless, and the provider's own sharp edges (GitHub code search only indexes the default branch; a bare common word returns nothing without a scope).

The blurb and the guide are two tiers of the same disclosure: list_tool_groups shows the one-line blurb, and loading the group delivers the full guide.

The home tile row​

packages/ui/src/home/IntegrationRow.tsx, between the greeting and the ask bar. Reuses the .provider-option / .provider-dot vocabulary so it reads as native to the page.

  • connected — full-colour mark, account in the tooltip
  • unconnected — grayscale(1), 55% opacity, + badge
  • error — full colour with an amber dot; the popover explains
  • backend down — renders nothing. Home already has one backend-down message and a second would be noise.

Clicking a tile opens a popover (outside-click + Escape to close) showing the granted scopes and a Disconnect, or the connect flow when unconnected. Here it is anchored under the tile that opened it; reached from anywhere else it is the same component centred in a shell dialog — see below.

The row appears twice: standalone above the ask bar, and as step 3 of the setup flow while nothing is connected — see Onboarding, which also explains why the account and the connectors are deliberately separate steps.

State lives in the shared store (packages/core/src/connectors/store.ts), not in this component. Two consequences worth knowing:

  • Any pane can ask useConnector('github') instead of calling the backend and rendering whatever a 409 says, and can wrap itself in ConnectionGate to offer the connect flow rather than a dead end.

  • ConnectorPopover is the only connect UI, but the row is not the only place it appears. requestConnect(id) from anywhere is answered by ConnectorDialog (packages/ui/src/home/ConnectorDialog.tsx), mounted at the shell next to Dialogs, which renders the same component as a centred modal (variant="modal"). So a pane never grows a second copy of the flow and never has to navigate to find it.

    It works this way because the alternative was tried: the taskbar clock flyout's integration tiles used to run shell.setup, which switched the desktop backdrop to the splash surface — where the row is mounted — and reset the setup card, dropping the connector id on the way. Clicking "Experiment trackers" from the clock landed you on the greeting with nothing open and the tile to find again. A connect request should never be a navigation.

The popover checks whether the consent page actually opened. A blocked window used to leave it reading "Finish signing in on the tab that opened" — a claim about a tab that does not exist — while the poll ran its full expiry against a page nobody had seen.

Testing​

  • backend/tests/test_scrive_crosspost.py — dev.to's key check and header, Hashnode's publication choice, bare token and GraphQL errors (with the Scrive outbox).
  • backend/tests/test_connectors.py — the tile projection, all three kinds, the naming invariant, "a token is never in the payload".
  • backend/tests/test_connectors_oauth.py — state/PKCE rejection, the device flow, refresh (including that concurrent callers refresh exactly once).
  • backend/tests/test_connectors_google.py — the PKCE authorize URL, code exchange, refresh, and that a client secret never resolves from settings.
  • backend/tests/test_connectors_huggingface.py — the device flow, that refresh survives a response omitting the refresh token, that the scope set stays read-only, and the dataset-namespace / binary-file / gated-repo edges of its tools.
  • backend/tests/test_google_sync.py — pagination, incremental runs, no duplicate sources, removal handling, the configurable library.
  • backend/tests/test_drive_pdf.py — PDF extraction against real PDF bytes, including the scanned-document case.
  • backend/tests/test_secrets_store.py — key resolution and the decrypt-failure contract.
  • packages/core/src/connectors/__tests__/api.test.ts — the polling loop.

The one connector that is not an account — it is key custody for the search module's metered engines: Tavily, Brave, Exa and Serper.

One connector, four keys, because a connector's id must equal its agent-tool prefix. Four connectors would mean tavily.search, brave.search, … — four tool groups and four catalog blurbs for a single capability, and no provider-agnostic tool for the model to call. One search connector gives one search.* group whose engine is an implementation detail the user can switch without the agent noticing.

The connect flow is a single form step with one optional secret field per engine. There is no select field type in the connect-form vocabulary, so engine choice could not live here anyway — and it shouldn't: a vendor's name is public, so search.provider is an ordinary setting. Only the key is secret, and keys are stored under search:<provider> in secrets.db, never echoed back into a form prefill or a status payload.

Environment variables win over stored keys (SEARCH_TAVILY_API_KEY and friends). A pinned field says so in its help text and its submitted value is discarded rather than persisted — storing a value that will never be read is worse than doing nothing, because it looks like it worked.

connected means "you added paid engines", not "search works"

The search.* tools are registered unconditionally, and SearXNG and the keyless DuckDuckGo fallback need no key at all — so search answers queries with this tile untouched. Conflating the two would push people into paying for something they already have.

A blank field on reconfigure means "leave it alone", never "clear it". The form cannot prefill a secret, so blank is the default state of a field whose key is already stored; treating it as a delete would wipe a working key every time someone opened the tile.

NVIDIA​

An api-key connector (NGC issues personal keys and has no device flow) holding one credential with two uses: the NGC model catalog and NIM, NVIDIA's hosted inference.

A NIM endpoint is one PROVIDERS entry with dialect="openai", not a new dialect. NIM speaks the OpenAI chat API; a bespoke dialect would mean six new branches in providers.py and would silently lose the tool_choice="required" retry, which is gated on info.dialect == "openai" — the same reasoning the llama.cpp integration records. It is the first openai-dialect provider that is remote, so auth_headers was added to the shared request path: empty for every local server, a Bearer for NIM.

It is an ordinary hosted provider in GET /api/agent/status: listed with or without a key, unreachable until one exists, pointing at build.nvidia.com. It used to be filtered out until the connector held a key, following the peer precedent — but peer is a provider nobody can obtain on purpose, whereas anyone can get an NVIDIA key, so hiding it meant nothing anywhere in the agent settings said this node can talk to NVIDIA at all. The request that filter was avoiding — an unauthenticated call on every status poll — is instead prevented by the MissingApiKey check in list_models, which now fires before the dialect branch rather than inside the litellm one, because "a hosted provider without a key is not reachable" was never a litellm-only rule.

ProviderInfo.key_connector is how the provider borrows the credential: non-empty means api_key_for reads that connector's store, and means the key-write routes (PUT/DELETE /api/agent/providers/<kind>/key) refuse this provider with a 400 naming the connector. One home — NVIDIA's key reaches NIM inference and the NGC catalog, so a second copy under the provider kind would be a second thing to rotate, a second thing to leak, and would skip the connector's own verification, which is what proves a pasted key actually works. The API-keys settings section renders such a provider as a status row saying where the credential lives, rather than a field the backend would reject.

store.save takes a Credential dataclass, not a dict. This connector was written against a dict-shaped store that does not exist, so pasting a key raised TypeError: asdict() should be called on dataclass instances before anything was written — the connector had never worked, and nothing caught it because nothing tested it (backend/tests/test_connectors_nvidia.py now does).

NVIDIA publishes no per-model price signal. /v1/models is the plain OpenAI shape (id, owned_by, root) with no pricing, and the Free Endpoint badge on build.nvidia.com is rendered server-side with no JSON API behind it — NGC's catalog search is a different universe (downloadable registry artifacts). So unlike OpenRouter, whose pricing.prompt/pricing.completion decide free_models, a free tag for NIM cannot be derived, and one is not invented. What it gets instead is ProviderInfo.tier_note — one sentence about the tier, rendered once beneath the model list in the picker (for the providers whose rows are actually in view) rather than on each row. The distinction is the point: the note is true of the provider, and repeating it per model would read as a claim about that model in particular, which is exactly the claim nothing supports. free_models stays empty for NIM.

Connecting NVIDIA has nothing to do with the hardware probe. That reads the card in this machine with nvidia-smi; this is an account.

Hugging Face gained a write scope​

write-repos was added so a finished checkpoint or a dataset built here can be pushed to the Hub (huggingface.createRepo, huggingface.uploadFolder).

manage-repos is still deliberately absent, and that distinction is the whole safety argument the original "read-only" rule was really protecting: write-repos can create a repo and upload files; manage-repos can delete one. A confused agent that uploads a bad checkpoint has wasted bandwidth; one that can delete a repo has destroyed work.

Adding a scope forces re-consent. A connection made before write-repos existed keeps working for reads, and a push tells it to reconnect rather than failing with a bare 403 several megabytes in. The check order matters: not connected is reported before read-only, or a disconnected account goes looking for a scope problem it does not have.