Providers

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 provider list-profiles

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

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 --from-existing

This reads ANTHROPIC_API_KEY or CLAUDE_API_KEY from your current environment and stores them in the provider.

With Explicit Credentials

Supply a credential value directly:

$
openshell provider create --name my-api --type generic --credential API_KEY=sk-abc123

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-api --type generic --credential API_KEY

This looks up the current value of $API_KEY in your shell and stores it.

Provider profile metadata is available for known provider types. Provider profile network policy is gateway opt-in:

$
openshell settings set --global --key providers_v2_enabled --value true

Without providers_v2_enabled=true, provider behavior remains credential-only.

When providers_v2_enabled=true, --from-existing uses profile-backed discovery instead of the legacy provider registry. The requested --type must have a built-in or imported provider profile with a discovery section. If no matching profile exists, the CLI returns an error instead of falling back to legacy discovery.

Update a custom provider profile after exporting it, editing its endpoints, binaries, or credential metadata, and preserving the exported resource_version:

$
openshell provider profile export my-api -o yaml > my-api-profile.yaml
$
openshell provider profile update my-api -f my-api-profile.yaml

Import remains create-only and fails if the profile ID already exists. Use provider profile update <id> for existing custom profiles. Built-in 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. When providers_v2_enabled=true, updated profile policy applies to all provider instances of that type on the next sandbox config sync.

Manage Providers

List, inspect, update, and delete providers from the active gateway.

List all providers:

$
openshell provider list

Use -o json or -o yaml for machine-readable output:

$
openshell provider list -o json
$
openshell provider list -o yaml

Structured output includes provider 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. For details on how credentials are injected into sandboxes, refer to Credential Injection.

Inspect a provider:

$
openshell provider get my-claude

Update a provider’s credentials:

$
openshell provider update my-claude --from-existing

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=1767225600000

Use 0 as the timestamp to clear expiry for a credential key.

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 1767225600000

Pass 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-graph

Delete refresh metadata for a credential:

$
openshell provider refresh delete my-graph \
>
  --credential-key MS_GRAPH_ACCESS_TOKEN

Force a gateway-managed refresh for one credential:

$
openshell provider refresh rotate my-graph --credential-key MS_GRAPH_ACCESS_TOKEN

AWS STS

AWS STS refresh requires providers_v2_enabled=true. 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 settings set --global --key providers_v2_enabled --value true --yes
$
$
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_ID

The 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_KEY

Pass 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-claude

Attach Providers to Sandboxes

Pass one or more --provider flags when creating a sandbox:

$
openshell sandbox create --provider my-claude --provider my-github -- claude

Each --provider flag attaches one provider. The sandbox receives all credentials from every attached provider at runtime. Profile-managed providers also contribute provider-generated network policy entries when providers_v2_enabled is enabled at the gateway. When the setting is disabled, providers keep the previous behavior and only provide credentials.

Auto-Discovery Shortcut

When providers_v2_enabled=false and the trailing command in openshell sandbox create is a recognized tool name (claude, codex, or opencode), the CLI auto-creates the required provider from your local credentials if one does not already exist. You do not need to create the provider separately:

$
openshell sandbox create -- claude

This detects claude as a known tool, finds your ANTHROPIC_API_KEY, creates a provider, attaches it to the sandbox, and launches Claude Code.

Providers v2 disables command-derived provider inference. When providers_v2_enabled=true, create or import the provider profile, create the provider instance, and pass --provider <name> explicitly.

How Credential Injection Works

The agent process inside the sandbox never sees real credential values. At startup, the proxy replaces each credential with an opaque placeholder token in the agent’s environment. When the agent sends an HTTP request containing a placeholder, the proxy resolves it to the real credential before forwarding upstream.

This resolution requires the proxy to see plaintext HTTP. Endpoints must use protocol: rest in the policy (which auto-terminates TLS) or explicit tls: terminate. Endpoints without TLS termination pass traffic through as an opaque stream, and credential placeholders are forwarded unresolved.

Supported injection locations

The proxy resolves credential placeholders in the following parts of an HTTP request:

The proxy does not modify request bodies, cookies, or response content.

Fail-closed behavior

If the proxy detects a credential placeholder in a request but cannot resolve it, it rejects the request with HTTP 500 instead of forwarding the raw placeholder to the upstream server. This prevents accidental credential leakage in server logs or error responses.

Example: Telegram Bot API (path-based credential)

Create a provider with the Telegram bot token:

$
openshell provider create --name telegram --type generic --credential TELEGRAM_BOT_TOKEN=123456:ABC-DEF

The agent reads TELEGRAM_BOT_TOKEN from its environment and builds a request like POST /bot<placeholder>/sendMessage. The proxy resolves the placeholder in the URL path and forwards POST /bot123456:ABC-DEF/sendMessage to the upstream.

Example: Google API (query parameter credential)

$
openshell provider create --name google --type generic --credential YOUTUBE_API_KEY=AIzaSy-secret

The agent sends GET /youtube/v3/search?part=snippet&key=<placeholder>. The proxy resolves the placeholder in the query parameter value and percent-encodes the result before forwarding.

Supported Provider Types

The following provider types are supported.

Supported Inference Providers

The following providers have been tested with inference.local. Any provider that exposes an OpenAI-compatible API works with the openai type. Set --config OPENAI_BASE_URL to the provider’s base URL and --credential OPENAI_API_KEY to your API key.

Refer to your provider’s documentation for the correct base URL, available models, and API key setup. For the Vertex-specific auth flows and config keys, refer to Google Vertex AI. To configure inference routing, refer to Inference Routing.

Next Steps

Explore related topics:

• To manage workspace access for providers, refer to Manage Workspaces and Access.
• To control what the agent can access, refer to Policies.
• To use the base sandbox container, refer to Sandboxes.
• To view the complete field reference for the policy YAML, refer to the Policy Schema Reference.