OpenShell/docs/sandboxes/manage-providers.mdx

---
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
title: "Providers"
sidebar-title: "Providers"
description: "Create and manage credential providers that inject API keys and tokens into OpenShell sandboxes."
keywords: "Generative AI, Cybersecurity, Providers, Credentials, API Keys, Sandbox, Security"
position: 3
---

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.

<Info>
Providers v2 is available for profile-backed provider policy, provider-owned network rules, and gateway-managed credential refresh. This page remains the credential-focused provider command reference. For the new workflow, see [Providers v2](/sandboxes/providers-v2).
</Info>

Provider profiles include metadata for known endpoints and binaries. View
the available profiles before creating a provider:

```shell
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:

```shell
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:

```shell
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:

```shell
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:

```shell
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`:

```shell
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:

```shell
openshell provider list
```

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

```shell
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](#how-credential-injection-works).

Inspect a provider:

```shell
openshell provider get my-claude
```

Update a provider's credentials:

```shell
openshell provider update my-claude --from-existing
```

Set or clear a credential expiry timestamp:

```shell
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:

```shell
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:

```shell
openshell provider refresh status my-graph
```

Delete refresh metadata for a credential:

```shell
openshell provider refresh delete my-graph \
  --credential-key MS_GRAPH_ACCESS_TOKEN
```

Force a gateway-managed refresh for one credential:

```shell
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.

```shell
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:

```shell
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:

```shell
openshell provider delete my-claude
```

## Attach Providers to Sandboxes

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

```shell
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.

<Warning>
Legacy provider attachment is fixed at sandbox creation time. Providers v2 adds
`openshell sandbox provider attach` and `openshell sandbox provider detach` for
running sandboxes. See [Providers v2](/sandboxes/providers-v2#attach-and-detach-providers)
for runtime attach and detach behavior.

</Warning>

### 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:

```shell
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:

| Location | How the agent uses it | Example |
|---|---|---|
| Header value | Agent reads `$API_KEY` from env and places it in a 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>` |
| Query parameter value | Agent places the placeholder in a URL query parameter. | `GET /api?key=<placeholder>` |
| URL path segment | Agent builds a URL with the placeholder in the path. Supports concatenated patterns. | `POST /bot<placeholder>/sendMessage` |

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:

```shell
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)

```shell
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.

| Type | Environment Variables Injected | Typical Use |
|---|---|---|
| `anthropic` | `ANTHROPIC_API_KEY` | Anthropic API |
| `aws-bedrock` | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `AWS_REGION` | AWS Bedrock InvokeModel via a translating bridge. Today the router does not inject any auth header; the configured `BEDROCK_BASE_URL` upstream is expected to handle auth itself. Refer to [Inference Routing](/sandboxes/inference-routing). |
| `claude` | `ANTHROPIC_API_KEY`, `CLAUDE_API_KEY` | Claude Code, Anthropic API |
| `codex` | `OPENAI_API_KEY` | OpenAI Codex |
| `copilot` | `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN` | GitHub Copilot CLI |
| `deepinfra` | `DEEPINFRA_API_KEY` | DeepInfra inference API |
| `generic` | User-defined | Any service with custom credentials |
| `github` | `GITHUB_TOKEN`, `GH_TOKEN` | GitHub API and `gh` CLI. Refer to [GitHub Sandbox](/get-started/tutorials/github-sandbox). |
| `gitlab` | `GITLAB_TOKEN`, `GLAB_TOKEN`, `CI_JOB_TOKEN` | GitLab API, `glab` CLI |
| `nvidia` | `NVIDIA_API_KEY` | NVIDIA API Catalog |
| `openai` | `OPENAI_API_KEY` | Any OpenAI-compatible endpoint. Set `--config OPENAI_BASE_URL` to point to the provider. Refer to [Inference Routing](/sandboxes/inference-routing). |
| `opencode` | `OPENCODE_API_KEY`, `OPENROUTER_API_KEY`, `OPENAI_API_KEY` | OpenCode |

<Note>
`ANTHROPIC_API_KEY` is an API key from [console.anthropic.com](https://console.anthropic.com), not a subscription token. Subscription users must generate a separate API key from the Anthropic Console.
</Note>

<Tip>
Use the `generic` type for any service not listed above. You define the
environment variable names and values yourself with `--credential`.

</Tip>

## 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.

| Provider | Name | Type | Base URL | API Key Variable |
|---|---|---|---|---|
| AWS Bedrock (via bridge) | `bedrock-bridge` | `aws-bedrock` | Operator-supplied `BEDROCK_BASE_URL` | None at router level (bridge holds creds) |
| NVIDIA API Catalog | `nvidia-prod` | `nvidia` | `https://integrate.api.nvidia.com/v1` | `NVIDIA_API_KEY` |
| Anthropic | `anthropic-prod` | `anthropic` | `https://api.anthropic.com` | `ANTHROPIC_API_KEY` |
| Google Vertex AI | `vertex-prod` | `google-vertex-ai` | Regional, global, or multi-region Vertex endpoint | `GOOGLE_VERTEX_AI_TOKEN` or `GOOGLE_VERTEX_AI_SERVICE_ACCOUNT_TOKEN` |
| Baseten | `baseten` | `openai` | `https://inference.baseten.co/v1` | `OPENAI_API_KEY` |
| Bitdeer AI | `bitdeer` | `openai` | `https://api-inference.bitdeer.ai/v1` | `OPENAI_API_KEY` |
| DeepInfra | `deepinfra` | `deepinfra` | `https://api.deepinfra.com/v1/openai` | `DEEPINFRA_API_KEY` |
| Groq | `groq` | `openai` | `https://api.groq.com/openai/v1` | `OPENAI_API_KEY` |
| Ollama (local) | `ollama` | `openai` | `http://host.openshell.internal:11434/v1` | `OPENAI_API_KEY` |
| LM Studio (local) | `lmstudio` | `openai` | `http://host.openshell.internal:1234/v1` | `OPENAI_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](/providers/google-vertex-ai). To configure inference routing, refer to [Inference Routing](/sandboxes/inference-routing).

## Next Steps

Explore related topics:

- To control what the agent can access, refer to [Policies](/sandboxes/policies).
- To use the base sandbox container, refer to [Sandboxes](/sandboxes/manage-sandboxes#base-sandbox-container).
- To view the complete field reference for the policy YAML, refer to the [Policy Schema Reference](/reference/policy-schema).