Sources and Supply-chain Security

SDK/model download sources and project dependency registries are separate control planes in osdk. This page covers download sources, offline mode, pre-releases, checksums, signatures, GitHub attestations, and the generic GitHub Release backend. For npm-compatible registries, see JavaScript Package Managers.

Source command reference

osdk source list TOOL_OR_PROVIDER
osdk source test TOOL
osdk source test huggingface|modelscope|civitai --model REFERENCE

osdk source add TOOL_OR_PROVIDER
  --id ID
  --download-url URL
  [--index-url URL]
  [--forward-credentials]

osdk source remove TOOL_OR_PROVIDER ID
osdk source pin TOOL_OR_PROVIDER ID
osdk source unpin TOOL_OR_PROVIDER

Command or argument	Effect
list TOOL_OR_PROVIDER	List effective sources, types, URLs, and the pin
test TOOL_OR_PROVIDER	Force a probe for an SDK backend and print throughput/TTFB ranking
test TOOL_OR_PROVIDER --model ...	Probe Hugging Face/ModelScope repository or exact Civitai LoRA-version metadata and a file sample
add TOOL_OR_PROVIDER --id ID --download-url URL	Add or replace a user-global custom source with that ID
--index-url URL	Use a separate metadata/index endpoint
--forward-credentials	Permit a custom model endpoint to receive provider credentials
remove TOOL_OR_PROVIDER ID	Remove a user-global custom source
pin TOOL_OR_PROVIDER ID / unpin TOOL_OR_PROVIDER	Set or remove a source pin in user configuration

add, remove, pin, and unpin all edit user config.toml. --source ID is an invocation-only preference that retains other sources as fallbacks. Tool requests in that invocation must use the canonical backend ID, such as node rather than nodejs, or the current implementation will not apply the override. --refresh-sources forces re-probing for install, use, upgrade, and exec. For model sync, it refreshes only when no explicit endpoint or pin applies, selection is auto, and offline mode is disabled. It currently has no effect on lock, outdated, or list-remote. Model source test fails without --model, and --model is invalid for an SDK tool.

Mirrors set in the environment

Every toolchain has its own way to point at a mirror through the environment: rustup reads RUSTUP_DIST_SERVER (and RUSTUP_UPDATE_ROOT), the go command reads GOPROXY, and the npm family reads npm_config_registry, pnpm_config_registry, YARN_REGISTRY, YARN_NPM_REGISTRY_SERVER, BUN_CONFIG_REGISTRY, and friends.

By default (mode = "auto") osdk validates such a value and then ranks it together with its built-in mirrors, picking the fastest measured one, instead of obeying it unconditionally:

• when validation fails (not a valid URL, not https, embedded credentials, or a query string or fragment) osdk prints a warning and ignores the value, falling back to its built-in mirrors rather than dropping it silently;
• when validation passes the value joins the probe as a candidate with the id env, visible in osdk source list <tool>; if it matches a built-in mirror's endpoint it is not listed twice;
• GOPROXY values such as off, direct, and comma- or pipe-separated fallback lists are legitimate go settings but are not a single probeable mirror, so they are skipped with an explanation.

To obey the environment unconditionally — for example a corporate mirror that must be used even when it is slower — pass --source-mode env. In that mode a missing or unusable value is an error rather than a silent fallback, so a misconfiguration cannot pass unnoticed.

Precedence: an explicit choice always beats the environment. osdk source pin and the one-shot --source ID still win; the environment only competes when nothing was chosen deliberately.

Effective source list

[sources]
selection = "auto"       # auto|pinned|ordered
mode = "auto"            # auto|env, see "Mirrors set in the environment"
probe_timeout_ms = 1500        # SDK/tool probes
model_probe_timeout_ms = 8000  # each model metadata/header/sample phase
cache_ttl = "6h"

[sources.node]
pin = "corp"
disable = ["tuna"]

[[sources.node.custom]]
id = "corp"
kind = "custom"          # official|mirror|custom
download_url = "https://mirror.example/node/"
index_url = "https://mirror.example/node/index.json"
headers = [["X-Example", "value"]]
forward_credentials = false
priority = 0
enabled = true

The effective list is built-ins minus disable, plus custom. A custom source with the same ID overrides a built-in, enabled=false entries are filtered, and smaller priority values come first. Civitai includes two official sources: official (civitai.com) and official-red (civitai.red). source pin can fix either one, while auto mode ranks them for the exact requested version. Project source settings require explicit trust.

headers is explicit source configuration and is separate from forward_credentials. Metadata requests and source probes made by osdk attach these headers only when the initial URL has the source's configured index/download origin. They survive same-origin redirects, are permanently removed after the first cross-origin redirect, and their clear values are not written to cache. The managed npm and pnpm delegates receive only a registry override and an otherwise empty, osdk-owned configuration, so actual npm:<package> package fetches do not forward Source.headers. Project package-manager invocations may use native trusted configuration, but global npm tools reject authenticated/private native pass-through while their prefix is isolated; use an anonymous configured registry for global installs.

Selection, probing, and failover

selection	Behavior
auto	Reuse a ranking inside the TTL or probe in parallel; rank primarily by throughput with a TTFB penalty
ordered	Keep priority order without probing
pinned	Behave like ordered when no concrete sources.<tool>.pin exists

A concrete pin moves that source to the front but retains every other source as a failure fallback; it is not strict “only this source” enforcement. SDK/tool probes default to 1500 ms. Model probes instead use model_probe_timeout_ms = 8000 as an independent budget for each metadata, response-header, and 64 KiB sample phase. They choose the smallest non-empty repository file. A successful response marks the source reachable even if sample body reading exceeds its budget; throughput is then unknown, not unreachable. An all-failed model probe set is not cached for the normal 6-hour TTL, so a brief outage cannot pin every source as dead. An invalid TTL currently falls back silently to 6 hours.

Downloads performed by osdk itself use the shared streaming pipeline rather than failing after one request. Regular archives retain three attempts with 400 ms and 800 ms backoff. Model files default to six attempts with visible warnings and 1/2/4/8/8-second exponential backoff; sources.model_download_attempts and sources.model_download_retry_base_ms are configurable through osdk config set. sources.model_read_timeout_ms (default 60000) bounds the no-progress interval, so a connection that stalls mid-transfer fails that request into the retry above instead of hanging forever. A .partial file and its ETag/Last-Modified metadata are retained, so a retry resumes with Range + If-Range; an ignored or invalid range, changed object, or changed source URL restarts safely. A source probe only ranks candidates; it does not prove that an exact version exists, and even HTTP 200 can be a mirror error page. For archives, standalone binaries, and self-update assets handled directly by osdk, download, checksum/attestation verification, extraction, and required-file checks are one candidate attempt. Failure at any stage discards that candidate and tries the next ranked source; the receipt records only the URL that passed the full attempt. Model downloads likewise try the remaining ranked sources after one source exhausts its attempts. Exhausting every source remains terminal.

Delegated installers cannot all be handled by blindly rerunning a failed command, because an install script may already have produced side effects. osdk therefore fails over at safe, ecosystem-specific boundaries: Rust reruns the complete rustup download operation per source; Cargo checks the exact crate version's config.json download endpoint before committing to a sparse index; pypi: probes the requested project page rather than a fixed pip page and passes the selected index to uv/pip; and go: supplies one native GOPROXY chain joined with |. Ordinary project npm/uv/pip commands still execute once and are not blindly replayed after a possible lifecycle script. Online metadata access may use stale cache after a request failure; strict offline mode only reads existing cache, while still re-verifying and unpacking the cached artifact.

Offline mode

osdk --offline install bun@1.3.14
osdk --offline install                    # may consume the current-platform lock
osdk --offline model sync qwen

--offline or OSDK_OFFLINE=true strictly prohibits network access:

• metadata, SDK archives, model metadata, and every selected file must be cached;
• automatic source probes are skipped; source test and --refresh-sources on SDK-installing commands fail, model sync does not refresh, and commands that do not support the flag continue to ignore it;
• a cache miss fails explicitly instead of going online;
• for backends with a generic artifact receipt, a lock's artifact URL/checksum can support offline reinstall; bytes are reverified when the pipeline actually reinstalls with a checksum, while an existing complete GitHub installation is reused only when its receipt also matches the locked filename/checksum and its dynamic option identity matches;
• npm:<package> does not use a generic artifact URL. The schema-4 osdk.lock retains the schema-3 npm metadata model: it stores only scope, installer, and optional native-lock identity, not the dependency graph, so that metadata alone cannot cold-restore the graph. A complete install can be reused only when its recorded options match; operations that support native-lock replay additionally need the installer-owned lock and a warmed cache/store. Legacy lock-schema-2 graph sidecars are compatibility-read inputs only;
• cargo: tools can reuse an already complete installation only when source, selector, options, platform, and exact managed Rust identity all match. A cold offline install or repair is unsupported because neither the Cargo native lock nor osdk.lock contains the complete source graph;
• go: tools can likewise reuse only an exact complete installation. Their schema-4 lock records the selected Go proxy, discovered module root, public build options, and exact managed Go identity, but not the transitive module graph needed for a cold offline build;
• attestations=required additionally needs the proof bundle cached by artifact SHA-256; lock evidence cannot replace verification.

OSDK_OFFLINE controls osdk and compatible environment values managed by its hooks. Whether a project subprocess is completely offline still depends on that downstream tool's native options.

Pre-releases

osdk install bun@canary
osdk install deno@beta
osdk install github:owner/repo@1.2.0-beta.1
osdk --prerelease allow install bun@latest
osdk --prerelease never install bun@canary

Policy	Behavior
never	Reject every pre-release, including an explicit version or channel
if-explicit	Default; allow a pre-release only through an explicit version or `canary
allow	Permit latest, prefixes, and ranges to select a pre-release implicitly

The policy applies to pre-release-aware Python, Bun, Deno, and GitHub backends. list-remote still lists only stable versions. Locks preserve both the original request and the exact resolved version. Cargo registry resolution has its own fixed rule: yanked releases are always removed, latest and numeric prefixes select stable releases, and only an exact Cargo selector can select an explicit non-yanked prerelease.

Integrity, signatures, and Attestation

osdk --require-checksums install node@20
osdk --attestations if-available install github:cli/cli@latest
osdk --attestations required install github:cli/cli@latest

Ordinary checksums support SHA-256, SHA-512, and BLAKE3. npm SRI supports sha256- and sha512-, preferring SHA-512 when both exist. --require-checksums means an artifact must have either an ordinary checksum or a trusted artifact SHA-256 from a verified attestation. A discovered checksum is persisted with the archive cache and is checked again when the pipeline actually performs an offline reinstall.

settings.verify_signatures=true enables signature verification by default; set OSDK_VERIFY_SIGNATURES=false to disable it explicitly. This currently applies to Minisign manifests for backends with a built-in trusted public key, currently github:jdx/mise. A missing manifest/signature can fall through to other checksum mechanisms, but an invalid signature is a hard failure.

GitHub Artifact Attestation policies are:

Policy	Behavior
off	Default; do not query attestations
if-available	Absence is allowed; a discovered invalid, malformed, or repository-mismatched bundle fails
required	A valid bundle must be present

Verification binds the artifact SHA-256, owner/repo, GitHub Actions OIDC issuer, Fulcio certificate chain and SCT, DSSE subject, Rekor body/SET/checkpoint/ Merkle inclusion, and signing time. GitHub v0.3 TSA bundles instead verify the embedded GitHub trust root, timestamp, certificate chain, signature, digest, and repository claim. The proof API fetches at most 30 entries per request. Bundle URLs and redirects must be HTTPS; compressed input and expanded JSON are each limited to 8 MiB.

TLS certificate verification

TLS certificates are verified against the operating system trust store: the Windows certificate store, Keychain on macOS, and the usual OpenSSL locations on Linux. osdk does not carry its own copy of the root certificates.

The practical consequence is that certificate trust follows the machine. A corporate CA installed system-wide, or a revoked root removed by an OS update, is picked up without waiting for an osdk release, which is what makes osdk usable behind a TLS-inspecting proxy. In exchange osdk depends on the host being provisioned: a minimal container image with no ca-certificates package will fail every HTTPS download until root certificates are installed.

Verification cannot be turned off. Downloads from an untrusted, expired, self-signed, or wrong-host certificate fail before any bytes are written, and the error names the specific reason.

Arbitrary GitHub Release tools

github:owner/repo[@VERSION]

osdk use -g github:sharkdp/fd
osdk install github:cli/cli@2.62.0
osdk list-remote github:sharkdp/fd

Asset selection options

Pass every option through repeatable -o|--opt KEY=VALUE:

Option	Values and effect
asset-regex=REGEX	Select by regex; exactly one asset must match
asset-template=TEMPLATE	Select an exact filename using {version}, {os}, {arch}, and {libc}
bin=PATH	Safe relative path to one binary inside an archive
bins=P1,P2	Multiple binary paths; mutually exclusive with bin
rename=NAME	Rename a single output binary; requires exactly one final bin
strip-components=N	Descend through N unique non-.osdk-* directories after extraction
os=VALUE	`linux
arch=VALUE	`x64
libc=VALUE	`gnu
catalog-url=URL_OR_PATH	Use a schema 1 static catalog and bypass the Releases API
catalog-sha256=HEX	Required with catalog-url; verifies exact catalog bytes
catalog-subdir=PATH	Record/restore an archive subdirectory for a locked artifact

asset-regex and asset-template are mutually exclusive. Without a rule, osdk scores by host OS, architecture, and archive type while excluding checksum, signature, and source assets. Zero or multiple matches fail. Unknown archive extensions are treated as bare binaries; Windows normalizes .exe. For osdk-owned GitHub installs, the supported asset, platform, catalog-digest, and layout options are part of the dynamic installation identity. catalog-url is accepted for acquisition but is excluded from the persisted dynamic identity; its required catalog-sha256 identifies the catalog content. HTTP(S) catalog URLs containing userinfo, a query, or a fragment are rejected so credentials cannot be persisted through this option. An unknown public option is rejected before installation, and an existing same-version install with legacy or different option identity is not executed. Each canonical identity is recorded in .osdk-install.json schema 1 with a b3-v2: install_id and receives its own fingerprinted root, so same-version variants coexist. Exact configured identity drives reuse, activation, shims, where, uninstall, and reshim; legacy .osdk-tool.json state is detected but never reused or executed.

osdk install github:owner/repo@1.2.3 \
  -o 'asset-regex=^tool-.*-linux-x64\.tar\.gz$' \
  -o bins=dist/tool,dist/toolctl -o strip-components=1

osdk install github:owner/repo@1.2.3 \
  -o 'asset-template=tool-{version}-{os}-{arch}.zip' \
  -o bin=tool.exe -o rename=mytool -o os=windows -o arch=x64

Static catalog

osdk lock github:owner/repo@latest \
  -o catalog-url=/approved/github-catalog.json \
  -o catalog-sha256=0123456789abcdef...

A catalog can be HTTP(S), file://, or a normal local path. Every schema 1 asset contains name, url, checksum, os, and arch, with optional libc; artifact URLs must be HTTP(S). Online HTTP catalogs are cached by digest, while offline mode reads that cache. Local files can be read offline directly.

GitHub access, failover, and tokens

Token priority is OSDK_GITHUB_TOKEN, GITHUB_TOKEN, then GH_TOKEN. Authorization is sent only to the exact api.github.com host and never to a proxy. The Releases API reads at most 10 pages of 100 entries. On anonymous rate limiting, public Atom and expanded-assets HTML can provide best-effort discovery of recent public releases; they are not a complete history.

Built-in github and ghproxy sources consistently cover API requests, release assets, Raw/Gist files, checksums/signatures, and attestation bundles, with ranked failover and no token forwarding. Proxy inputs are normalized to official URLs first so pins, cache keys, and identities do not depend on proxy spelling.