trending/OpenShell
1
0
Fork 0
mirror of https://github.com/NVIDIA/OpenShell.git synced 2026-10-26 06:52:57 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(website): sync dev docs from e585b49173

Browse Source
This commit is contained in:
github-actions[bot]
2026-10-12 17:27:47 +00:00
parent a3d3255572
commit 85e1fc8798
2 changed files with 22 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
fern/.docs-snapshots.yml
+3 -3
View File
@@ -1,8 +1,8 @@
snapshots:
dev:
source-ref: c4dc30dc1b01839a765361ed07fcde89397a258c
source-sha: c4dc30dc1b01839a765361ed07fcde89397a258c
version: 0.1.4.dev12
source-ref: e585b49173c70e28273c11bacb9f4b8f4df3b8e3
source-sha: e585b49173c70e28273c11bacb9f4b8f4df3b8e3
version: 0.1.4.dev13
latest:
source-ref: e1f3c82caa3ed3b65de22889ae7ef32a774878ef
source-sha: e1f3c82caa3ed3b65de22889ae7ef32a774878ef
fern/pages-dev/how-it-works/providers/profiles.mdx
+19
View File
@@ -367,6 +367,9 @@ credentials:
description: API access token
env_vars: [CUSTOM_API_TOKEN]
required: true
# Optional mode for external credential updaters that need one opaque
# placeholder to survive value-only provider revisions.
stable_placeholder: false
# Accepted values: basic, bearer, header, query, path.
# These fields describe static credential placement.
@@ -750,6 +753,22 @@ OpenShell skips expired provider credentials when it builds a sandbox provider e
The gateway sends a complete host, port, and path binding for every emitted static credential key. It derives bindings from profile endpoints or explicit sandbox policy endpoints for endpointless profiles. It withholds static credential keys from endpointless selected profiles that have no explicit policy binding. Supervisors reject other incomplete binding metadata and clear previously active provider material when a refresh fails validation. Refer to [Static Credential Endpoint Binding](#understand-static-credential-endpoint-binding) for matching, denial, lifecycle, and migration behavior.
### Keep an Externally Updated Placeholder Stable
An MCP client may configure its caller-assertion header once at startup using the reference supplied by OpenShell. A host service rotates the assertion and updates the provider before the old assertion expires. The client needs its next request to use the new assertion without restarting or reloading its environment reference. Gateway-managed token refresh already provides this continuity; `stable_placeholder` extends it to externally supplied static credentials.
Set `stable_placeholder: true` on a credential only when an external updater requires the workload to keep one opaque placeholder across value-only `provider update` revisions. Declare at least one `env_vars` alias for that credential. OpenShell still classifies the value as secret and resolves it only for hosts, ports, and paths in the credential's effective endpoint binding. An endpointless profile therefore needs an explicit sandbox-policy `credential_binding` before the gateway emits this metadata.
The setting defaults to `false`, preserving existing revision-scoped behavior. Ordinary credentials continue to work with older gateways. To enable stable placeholders, use a supporting gateway, supervisor, and profile client. The CLI and Go SDK check gateway support before importing or updating an opted-in profile; a failed support check leaves the profile unchanged. Raw API clients must check `LintProviderProfilesResponse.supports_stable_placeholder` before enabling the setting.
The gateway withholds opted-in credentials from supervisors that do not advertise support. Once a supervisor activates an external stable credential, a gateway response without support acknowledgment revokes static credentials instead of switching to revision-scoped delivery. This requirement survives failed refreshes and clears when an acknowledged snapshot removes the last external stable credential. Keep a supporting gateway for startup and supervisor reconstruction: older binaries can discard unknown profile fields, so an empty stable-key list on first contact does not prove support. Remove the opt-in and activate that change before downgrading the gateway.
Use the environment value issued by the supervisor. Do not construct a resolver string or a canonical environment-name alias. Once the supervisor installs a value update, the next request from a process holding its original placeholder resolves the current value. Saving the provider update alone does not establish supervisor activation. Expiry or an activated detach prevents the placeholder from resolving a credential.
The supervisor resolves the placeholder outside the workload. The sandbox receives the prepared environment through its authenticated boundary; the credential value remains with the supervisor.
The opaque placeholder is tied to the sandbox, provider instance, credential key, and effective endpoint binding. Updating only the credential value preserves the placeholder. Replacing the provider or changing its endpoint binding produces a new placeholder, so a running process cannot use its old placeholder for the replacement credential. Use the default `false` when value-only continuity is unnecessary. Profiles cannot combine `stable_placeholder: true` with gateway-managed refresh, credentials produced as another credential's refresh outputs, or `token_grant` because those credentials have a different lifecycle owner.
## Configure Credential Refresh
Refresh configuration is stored separately from the current injectable credential value. Non-secret refresh configuration remains in the refresh-state record. Secret material is resolved from the active credential driver only while the gateway mints a new short-lived token. The gateway writes the token back through credential storage and updates credential expiry metadata. If an OAuth issuer rotates its refresh token, the gateway stages the replacement through credential storage before committing the refresh generation and removes the previous handle afterward.