Providers
Create and manage credential providers that inject API keys and tokens into OpenShell sandboxes.
AI agents typically need credentials to access external services: an API key for the AI model provider, a token for GitHub or GitLab, and so on. OpenShell manages these credentials as first-class entities called providers.
Create and manage providers that supply credentials to sandboxes.
Provider profiles include metadata for known endpoints and binaries. View the available profiles before creating a provider:
openshell profile listopenshell profile describe githubCreate a Provider
Section titled “Create a Provider”Providers can be created from local environment variables or with explicit credential values.
For refresh-backed providers such as google-vertex-ai --from-gcloud-adc, openshell provider create now waits for the gateway to configure refresh metadata and mint the initial access token before it reports success.
From Local Credentials
Section titled “From Local Credentials”The fastest way to create a provider is to let the CLI discover credentials from your shell environment:
openshell provider create --name my-claude --type claude-code --from-existingThis reads ANTHROPIC_API_KEY or CLAUDE_API_KEY from your current environment
and stores them in the provider.
With Explicit Credentials
Section titled “With Explicit Credentials”Supply a credential value directly:
openshell provider create --name my-nvidia --type nvidia --credential NVIDIA_API_KEY=nvapi-exampleBare Key Form
Section titled “Bare Key Form”Pass a key name without a value to read the value from the environment variable of that name:
openshell provider create --name my-nvidia --type nvidia --credential NVIDIA_API_KEYThis looks up the current value of $NVIDIA_API_KEY in your shell and stores it.
From the Current OIDC Login
Section titled “From the Current OIDC Login”Profile-backed token-exchange providers can store the current gateway OIDC access token as their subject credential. The subject credential stays gateway-only and is not emitted into sandbox environment material or static credential bindings:
openshell provider create \ --name custom-api \ --type custom-api \ --from-oidc-tokenOpenShell infers the destination credential from the provider profile when the
profile has exactly one token_grant.subject_token.credential. If the profile
has more than one, pass --credential <key>. Refresh the stored subject token
later with:
openshell provider update custom-api --from-oidc-tokenThis copies the current OIDC access token and expiry from the active gateway login. This requires an active named gateway that was registered for OIDC. If the stored gateway access token is expired and a refresh token is available, the CLI refreshes it before storing the provider credential. It does not store the OIDC refresh token in the provider.
--from-existing uses profile-backed discovery. The requested --type must
name an imported provider profile with a discovery section. If no matching
profile exists, the CLI returns an error instead of falling back to legacy
discovery.
Create a provider whose profile requires no static credentials without a credential source:
openshell provider create --name public-pypi --type pypiProvider creation rejects profileless types. For a custom GitLab deployment, import a profile with the deployment’s endpoints and then create an instance using that profile ID. Existing profileless provider records remain usable, but OpenShell does not create new ones.
Update a custom provider profile after exporting it, editing its endpoints,
binaries, or credential metadata, and preserving the exported resource_version:
openshell profile export my-api -o yaml > my-api-profile.yamlopenshell profile update my-api -f my-api-profile.yamlImport remains create-only and fails if the profile ID already exists. Use
profile update <id> for existing profiles. Interceptor-managed
profiles are read-only. The target ID must match the profile ID in the file. Update accepts
one file at a time and rejects stale resource versions. Updated profile policy
applies to all provider instances of that type on the next sandbox config sync.
Delete one or more custom provider profiles by ID:
openshell profile delete custom-api custom-altWhen a multi-profile delete fails for one entry, the CLI reports that profile’s failure and continues with the remaining IDs. The command exits with an error after it attempts every requested deletion if any entry failed.
Retrieve Runtime Credentials
Section titled “Retrieve Runtime Credentials”An mTLS operator can call
openshell.v1.OpenShell/GetProviderCredentials through the
Python SDK,
TypeScript SDK, or a generated/raw
gRPC client. Select one explicit workspace, one provider by canonical name, and
between 1 and 32 runtime environment keys. For example, the request body for a
GitHub provider is:
{ "workspace_scope": { "workspace": "default" }, "name": "my-github", "credential_keys": ["GITHUB_TOKEN"]}The response maps each selected key to its value and optional
expiration_time. The gateway returns all selected values or an error. It
reuses sufficiently valid credentials and refreshes gateway-managed credentials
when necessary. minimum_remaining_lifetime accepts a protobuf duration up to
24 hours; omission or zero uses a five-minute safety margin. Non-expiring static
credentials satisfy the lifetime requirement. A credential that cannot meet the
requested lifetime causes the call to fail.
OAuth refresh-managed credentials return access tokens, never gateway-only
refresh tokens, client secrets, or signing material. Supervisor-side,
endpoint-specific, and SPIFFE-bound dynamic grants return FAILED_PRECONDITION.
Refresh effects can persist even if another selected key causes the request to
fail. An uncertain rotating-token exchange requires reauthorization or refresh
reconfiguration rather than an automatic retry.
Manage Providers
Section titled “Manage Providers”List, inspect, update, and delete providers from the active gateway.
List all providers:
openshell provider listUse -o json or -o yaml for machine-readable output:
openshell provider list -o jsonopenshell provider list -o yamlStructured list output is an envelope with providers and
next_page_token fields. Each provider includes metadata (id, name,
type), credential key names, config key names, labels, creation timestamp,
resource version, and credential expiration times. Only credential and config
keys are exposed, never values, preventing accidental credential leakage in
logs or output. Pass the returned token to --page-token to continue. For
details on how credentials are injected into sandboxes, refer to
Credential Injection.
Inspect a provider:
openshell provider get my-claudeUpdate a provider’s credentials:
openshell provider update my-claude --from-existingTo wait until attached sandboxes apply the updated credentials, add --wait:
openshell provider update my-claude --from-existing --wait --timeout 30 --output jsonThe update records which sandboxes are attached before saving the new credentials. Its result includes a change ID and outcome for each of those sandboxes. Sandboxes attached later are outside this wait. The timeout applies to the whole group; if any selected sandbox fails or times out, the command exits with an error and still reports each sandbox’s outcome. When no sandboxes are attached, it reports the saved change and an empty target list.
Credential refresh status tells you whether OpenShell obtained credentials. Provider readiness tells you whether the sandbox applied the credentials, policy, and environment for new processes. It does not test access to a backend model or cancel requests already sent upstream.
After an ordinary static credential update completes, launch a new client
process to use the updated reference. Existing processes keep their environment
references; readiness does not guarantee that they use the replacement value.
Credentials configured with
stable_placeholder: true
let processes already holding a stable reference use a value-only update after
the supervisor installs it. See
Runtime Limitations for
retained revision behavior. Acknowledged detach revokes retained references and
removes them from environments for future launches.
Set or clear a credential expiry timestamp:
openshell provider update my-graph \ --credential MS_GRAPH_ACCESS_TOKEN="$MS_GRAPH_ACCESS_TOKEN" \ --credential-expires-at MS_GRAPH_ACCESS_TOKEN=1767225600000Use 0 as the timestamp to clear expiry for a credential key.
Label a Provider
Section titled “Label a Provider”Attach labels when you create a provider to track environment or team ownership.
Repeat --label for each key-value pair. This example uses the imported pypi
profile, which requires no static credentials.
openshell provider create --name public-pypi --type pypi --label env=dev --label team=mlList providers that match every key-value pair in a comma-separated selector.
Filtering applies before pagination and only returns providers in the selected
workspace. Platform Admins can filter across workspaces with --all-workspaces.
openshell provider list --label-selector env=dev,team=mlopenshell provider list --all-workspaces --label-selector team=ml --output jsonopenshell provider get public-pypiget displays attached labels. JSON and YAML list output also include labels.
When continuing a paginated list with --page-token, keep the selector and
workspace scope unchanged.
API clients set CreateProviderRequest.provider.metadata.labels and filter with
ListProvidersRequest.label_selector. The gateway returns labels in
provider.metadata.labels. Provider updates preserve existing labels and do
not change them, so set labels during creation.
Credential Refresh
Section titled “Credential Refresh”Provider refresh stores non-injectable refresh material separately from the provider’s current credential values. The gateway can mint OAuth2 refresh-token tokens, OAuth2 client credentials tokens, Google service account JWT tokens, and AWS STS temporary credentials, then write the current access token back to the provider record for sandbox injection.
Configure refresh metadata for one injectable credential key:
openshell provider refresh configure my-graph \ --credential-key MS_GRAPH_ACCESS_TOKEN \ --strategy oauth2-client-credentials \ --material tenant_id="$TENANT_ID" \ --material client_id="$CLIENT_ID" \ --secret-material-env client_secret=CLIENT_SECRET \ --credential-expires-at 1767225600000Pass secret material with --secret-material-env KEY[=ENVVAR] (ENVVAR
defaults to KEY): the CLI reads the value from its own environment, so the
secret never appears in the host process table the way an expanded
--material KEY="$VALUE" argument would, and KEY is automatically marked
secret. Keep non-secret material on --material; --secret-material-key KEY
still marks a key supplied through --material as secret.
Check refresh status:
openshell provider refresh status my-graphDelete refresh metadata for a credential:
openshell provider refresh delete my-graph \ --credential-key MS_GRAPH_ACCESS_TOKENForce a gateway-managed refresh for one credential:
openshell provider refresh rotate my-graph --credential-key MS_GRAPH_ACCESS_TOKENShared Secret Material
Section titled “Shared Secret Material”Use a workspace secret when many providers share one secret, such as the
client secret of a confidential OAuth client that every user’s provider
refreshes through. The gateway reads the secret’s current value at each mint,
so updating the secret reaches every provider that references it without
reauthorizing users. OpenShell never injects workspace secrets into sandboxes,
and openshell secret get and openshell secret list never show their values.
A secret created without --allowed-endpoint is reveal-only: no refresh can
reference it, and only an operator can read it through the RevealSecret RPC.
Create the secret with the token endpoints it may be sent to:
openshell secret create acme-oauth-client \ --value-env CLIENT_SECRET \ --allowed-endpoint https://login.example.com/oauth/tokenReference it from refresh configuration with --material-secret KEY=SECRET:
openshell provider refresh configure alice-mcp \ --credential-key MCP_ACCESS_TOKEN \ --strategy oauth2-refresh-token \ --material client_id="$CLIENT_ID" \ --secret-material-env refresh_token=REFRESH_TOKEN \ --material-secret client_secret=acme-oauth-clientRotate the shared value with openshell secret update acme-oauth-client --value-file ./client-secret. The file is stored exactly as read, including
any trailing newline, so write it with printf '%s'. Each provider uses the
new value at its next refresh; openshell provider refresh rotate applies it
immediately.
These rules apply:
- Only secret material can come from a workspace secret, and never a
refresh_token, which each provider rotates on its own. - The token endpoint the refresh calls must be one of the secret’s allowed endpoints, and the gateway does not follow redirects for these requests. Allowed endpoints cannot change; create a new secret for a new endpoint.
- Workspace secrets work with the OAuth2 and Google service account
strategies, not
aws_sts_assume_role. openshell secret deletefails while a refresh references the secret. Runopenshell provider refresh inline-secretsto copy the current value into the provider’s own refresh material first. It keeps the current grant, including a rotated refresh token.- If credential storage fails during deletion,
openshell secret listshows the secret asdeletinguntil the gateway finishes the cleanup. Rerunopenshell secret deleteto retry it.
provider refresh status reports which secrets a credential references. The
gateway operator must enable workspace secrets with enable_workspace_secrets;
refer to Gateway Configuration.
AWS STS
Section titled “AWS STS”The gateway calls sts:AssumeRole and writes three short-lived credentials
(AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN) to the
provider record atomically.
The aws and aws-s3 profiles declare AWS_SECRET_ACCESS_KEY and
AWS_SESSION_TOKEN as additional_outputs of the AWS_ACCESS_KEY_ID refresh,
so all three credentials are gateway-minted. Create the provider with
--runtime-credentials — no placeholder credential is needed.
openshell provider create --name my-aws --type aws-s3 --runtime-credentials
openshell provider refresh configure my-aws \ --credential-key AWS_ACCESS_KEY_ID \ --strategy aws-sts-assume-role \ --material role_arn="arn:aws:iam::123456789012:role/SandboxS3Writer" \ --material session_name="openshell-sandbox"
openshell provider refresh rotate my-aws --credential-key AWS_ACCESS_KEY_IDThe gateway resolves its own AWS credentials using the default credential chain (instance role, IRSA, ECS task role, environment variables). For gateways not running on AWS, provide explicit IAM keys via refresh material:
openshell provider refresh configure my-aws \ --credential-key AWS_ACCESS_KEY_ID \ --strategy aws-sts-assume-role \ --material role_arn="arn:aws:iam::123456789012:role/SandboxS3Writer" \ --material aws_access_key_id="$AWS_ACCESS_KEY_ID" \ --secret-material-env aws_secret_access_key=AWS_SECRET_ACCESS_KEYPass the long-lived secret with --secret-material-env so the CLI reads it
from its own environment instead of expanding it into a process argument,
where it would be visible in the host process table.
For temporary source credentials (AWS SSO or a prior AssumeRole), also pass a
session token with --secret-material-env aws_session_token=AWS_SESSION_TOKEN.
It requires the aws_access_key_id and aws_secret_access_key pair.
Use the generic aws profile type for multi-service access and scope endpoints
via sandbox network policy. Use aws-s3 for S3-specific endpoint rules.
The proxy re-signs requests using SigV4 before forwarding to AWS. Both curl and Python boto3 are supported.
External refresh systems should continue to push new current credentials through
openshell provider update. The --credential-expires-at option works for
static credentials, externally refreshed credentials, and gateway-managed
refresh strategies.
Delete a provider:
openshell provider delete my-claudeDelete multiple providers by listing their names in one command:
openshell provider delete my-claude my-githubWhen a multi-provider delete fails for one entry, the CLI reports that provider’s failure and continues with the remaining names. The command exits with an error after it attempts every requested deletion if any entry failed.
Attach Providers to Sandboxes
Section titled “Attach Providers to Sandboxes”Pass one or more --provider flags when creating a sandbox:
openshell sandbox create --from registry.example.com/your-org/claude-agent:latest --provider my-claude --provider my-github -- claudeEach --provider flag attaches one provider. The sandbox receives eligible
credentials from every attached provider as placeholders at runtime. Each
static credential resolves only for endpoints in that provider’s profile, or
for explicitly bound sandbox policy endpoints when the profile is endpointless.
Profile-managed providers also contribute provider-generated network policy
entries. Endpoint binding independently limits where each static credential can
be resolved.
Provider attachment checks credential inspection against the latest saved sandbox
policy, falling back to the creation policy only when no revision exists. If a
current rule permits uninspected traffic to a credentialed endpoint, configure
L7 inspection or remove the rule before attaching the provider. Use
allow_uninspected_credentials: true only for an intentional exception.
Auto-Discovery Shortcut
Section titled “Auto-Discovery Shortcut”Name a provider with --provider. If no provider by that name exists and the
name matches an imported profile ID, the CLI creates one from local profile
discovery, so you do not need to create it separately:
openshell sandbox create --from registry.example.com/your-org/claude-agent:latest --provider claude-code -- claudeThis finds your ANTHROPIC_API_KEY, creates a claude-code provider, attaches
it to the sandbox, and launches Claude Code. Add --auto-providers to skip the
confirmation prompt, or --no-auto-providers to skip creation entirely.
A provider is attached only when you name it. OpenShell does not derive one from
the trailing command: a profile’s binaries list authorizes a binary to reach
that profile’s endpoints, which is not a statement that running the binary asks
for the provider. A sandbox with no providers is a normal, fully supported
state.
How Credential Injection Works
Section titled “How Credential Injection Works”At startup, OpenShell supplies each eligible provider credential as an opaque placeholder token in the agent’s environment. When the agent sends an HTTP request containing a placeholder, the proxy resolves it immediately before forwarding the request. Credential injection does not automatically scrub credential values from upstream responses, so send credentialed requests only to trusted endpoints. Operator retrieval is a separate export path described in Retrieve Runtime Credentials.
Static credential resolution has three independent authorization boundaries:
- Network policy must allow the calling binary and request destination.
- The credential binding must include the request host, port, and path. Profile
endpoints provide the binding by default. An endpointless profile can use a
sandbox policy endpoint that names the attached provider instance through
credential_binding.provider. - The request location must match the declared header, query parameter, or
path-template slot, or an explicitly enabled body/WebSocket rewrite policy.
Without placement metadata, static credentials resolve only in
Authorizationor through those explicit rewrite policies.
All three checks must pass. A provider profile endpoint does not grant network access unless provider policy composition or the sandbox’s own policy allows the request. A plain sandbox policy endpoint does not grant credential use unless the profile already covers it or the endpoint explicitly binds an endpointless provider.
Every static credential declared by a provider receives the complete endpoint set from that provider’s profile, or the explicitly bound sandbox policy endpoints for an endpointless profile.
Credential resolution requires the proxy to handle the request as HTTP. Raw
tls: skip and non-HTTP tunnels remain opaque and do not support credential
rewrite. Refer to Profiles
for endpoint matching and migration guidance.
Supported injection locations
Section titled “Supported injection locations”The proxy automatically enforces declared placement when the gateway and
supervisor support it. Moving a header credential into a query parameter, path,
or unrelated header is denied before forwarding. A supporting supervisor defaults
to Authorization when placement metadata is absent and rejects malformed
metadata. Custom placements require a supporting gateway and an explicit profile
declaration. Older supervisors keep their previous behavior.
| Location | How the agent uses it | Example |
|---|---|---|
| Declared header value | Agent reads $API_KEY from env and places it in the declared header. |
Authorization: Bearer <placeholder> |
| Header value (Basic auth) | Agent base64-encodes user:<placeholder> in an Authorization: Basic header. The proxy decodes, resolves, and re-encodes. |
Authorization: Basic <base64> |
| Declared query parameter value | Agent uses the profile’s query_param. |
GET /api?key=<placeholder> |
| Declared URL path slot | Agent uses the profile’s path_template, including concatenated patterns. |
POST /bot<placeholder>/sendMessage |
| AWS SigV4 signing | An endpoint configures credential_signing, and the proxy signs with the endpoint-bound AWS credentials. |
credential_signing: sigv4 |
The proxy does not rewrite cookies, response content, unsupported request bodies, or WebSocket binary frames.
Explicit endpoint policies can enable credential rewriting in request bodies
or WebSocket text messages. WebSocket text message rewriting requires
protocol: websocket. These flags do not authorize arbitrary query
parameters, path slots, or unrelated headers. See Profiles
for placement configuration and upgrade requirements.
Clients that parse JWT claims
Section titled “Clients that parse JWT claims”A trusted launcher can wrap an issued placeholder in a JWT-shaped alias when a client needs local account metadata. Keep the original placeholder suffix in the signature segment:
base64url(header).base64url(claims).OPENSHELL-RESOLVE-ENV-<issued-placeholder-suffix>For example, a placeholder beginning openshell:resolve:env:s becomes a JWT
whose signature begins OPENSHELL-RESOLVE-ENV-s, retaining the entire handle and
environment key. Use the placeholder supplied to the running workload; do not
substitute a bare environment key or manufacture a handle. OpenShell replaces
the entire alias with the resolved credential and preserves its endpoint,
authorization-epoch, and expiry checks. The claims supply local metadata only;
the alias is not a signed identity token or an upstream credential.
Fail-closed behavior
Section titled “Fail-closed behavior”If policy allows a request but the credential binding does not include the
request endpoint, the proxy rejects the request with HTTP 403 and the
credential_endpoint_mismatch reason. It emits a denied activity event and a
security finding without recording the secret, placeholder, environment key, or
query string.
Unknown, malformed, expired, or otherwise unresolved placeholders also fail closed instead of being forwarded to the upstream service.
Inspect an Endpoint Binding
Section titled “Inspect an Endpoint Binding”Export the profile used by a provider to inspect its credential boundary:
openshell profile export github -o yamlFor the GitHub example profile, GITHUB_TOKEN and GH_TOKEN can resolve for
the profile’s api.github.com:443 and github.com:443 endpoints. Even if a
sandbox policy allows uploads.example.com:443, sending either placeholder
there returns credential_endpoint_mismatch.
For another service, define the credential in its own provider profile. Put stable endpoints in the profile, or leave the profile endpointless and bind each concrete provider instance from sandbox policy. Refer to Profiles for the profile workflow and schema.
Available Provider Types
Section titled “Available Provider Types”The provider types available to --type are the IDs of the profiles you
imported. List them:
openshell provider list-profilesThe repository’s
providers/ directory
ships example profiles for GitHub, PyPI, and the major inference and agent
providers. Each file’s header states the credential environment variables it
declares, the binaries it authorizes, and the endpoints it grants. Read it,
adjust the binary paths for your image, and import your copy.
Inference Provider Access
Section titled “Inference Provider Access”Attach an inference provider to each sandbox that needs it and configure the workload to call the provider’s native endpoint. The workload, not OpenShell, selects the model and request timeout.
| Provider | Example profile | Native base URL | Credential variable |
|---|---|---|---|
| OpenAI | openai |
https://api.openai.com/v1 |
OPENAI_API_KEY |
| Anthropic | anthropic |
https://api.anthropic.com |
ANTHROPIC_API_KEY |
| NVIDIA API Catalog | nvidia |
https://integrate.api.nvidia.com/v1 |
NVIDIA_API_KEY |
| DeepInfra | deepinfra |
https://api.deepinfra.com/v1/openai |
DEEPINFRA_API_KEY |
| Google Vertex AI | google-vertex-ai |
Region and model dependent | GOOGLE_VERTEX_AI_TOKEN or GOOGLE_VERTEX_AI_SERVICE_ACCOUNT_TOKEN |
An OpenAI-compatible protocol does not make the openai profile safe for an
arbitrary host. Baseten, Bitdeer, Groq, Ollama, LM Studio, self-hosted NIM, and
other alternate endpoints need their own profile declaring the actual host,
port, credential, and allowed binaries. See
Inference for complete examples
and migration guidance.
Next Steps
Section titled “Next Steps”Explore related topics:
- To manage workspace access for providers, refer to Workspaces.
- To control what the agent can access, refer to Policies.
- To use the default workload image, refer to Sandboxes.
- To view the complete field reference for the policy YAML, refer to the Policy Schema Reference.
We are a Cloud Native Computing Foundation sandbox project.
Copyright OpenShell a Series of LF Projects, LLC
For website terms of use, trademark policy and other project policies please see lfprojects.org/policies/.