OpenShell/docs/sandboxes/providers.md

title, description, topics, tags, content

title	description	topics	tags	content
page nav Providers Providers	Create and manage credential providers that inject API keys and tokens into OpenShell sandboxes.	Generative AI Cybersecurity	Providers Credentials API Keys Sandbox Security	type difficulty audience how_to technical_beginner engineer data_scientist

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.

Create a Provider

Providers can be created from local environment variables or with explicit credential values.

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.

Manage Providers

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

List all providers:

$ openshell provider list

Inspect a provider:

$ openshell provider get my-claude

Update a provider's credentials:

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

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.

:::{warning} Providers cannot be added to a running sandbox. If you need to attach an additional provider, delete the sandbox and recreate it with all required providers specified. :::

Auto-Discovery Shortcut

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

Supported Provider Types

The following provider types are supported.

Type	Environment Variables Injected	Typical Use
claude	ANTHROPIC_API_KEY, CLAUDE_API_KEY	Claude Code, Anthropic API
codex	OPENAI_API_KEY	OpenAI Codex
opencode	OPENCODE_API_KEY, OPENROUTER_API_KEY, OPENAI_API_KEY	opencode tool
github	GITHUB_TOKEN, GH_TOKEN	GitHub API, gh CLI — refer to {doc}/tutorials/github-sandbox
gitlab	GITLAB_TOKEN, GLAB_TOKEN, CI_JOB_TOKEN	GitLab API, glab CLI
nvidia	NVIDIA_API_KEY	NVIDIA API Catalog
generic	User-defined	Any service with custom credentials
outlook	(none: no auto-discovery)	Microsoft Outlook integration

:::{tip} Use the generic type for any service not listed above. You define the environment variable names and values yourself with --credential. :::

Next Steps

Explore related topics:

• To control what the agent can access, refer to {doc}policies.
• To use a pre-built environment, refer to the {doc}community-sandboxes catalog.
• To view the complete field reference for the policy YAML, refer to the Policy Schema Reference.