> ## Documentation Index
> Fetch the complete documentation index at: https://www.1password.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect 1Password Environments to NVIDIA OpenShell for secure agent access (beta)

> Keep secrets out of agent context with 1Password and NVIDIA OpenShell.

export const BetaBadge = ({content}) => {
  if (content) {
    return <span className="op-beta-badge-inline not-prose">
        <span className="op-status-badge">Beta</span>
      </span>;
  }
  return <>
      <style>
        {`
        .mdx-content {
          margin-top: 4px !important;
        }
      `}
      </style>
      <span className="op-status-badge not-prose">Beta</span>
    </>;
};

<BetaBadge />

1Password for NVIDIA OpenShell (beta) lets an agent use the developer secrets it needs without those secrets entering the agent's context. You connect a [1Password Environment](/environments) to an OpenShell gateway, then attach it to the sandbox where the agent runs.

Inside the sandbox, the agent only ever works with placeholder values. When it sends a request to a host you've approved, the gateway replaces the placeholders with the real secrets outside the sandbox and forwards the request. Requests to any other host don't receive the credential.

You choose how long OpenShell keeps custody of the secrets. After that window expires, the sandbox keeps running but the gateway stops replacing placeholders, so requests that need the secrets fail.

## Requirements

* A 1Password account.
* The [latest nightly release](https://support.1password.com/betas/?mac#install-a-prerelease-version-of-the-1password-app) of 1Password for Mac or Linux.
* [NVIDIA OpenShell <Icon icon="arrow-up-right-from-square" />](https://docs.nvidia.com/openshell/about/installation) installed, with a running gateway.
* A coding agent that OpenShell supports, like Claude Code.

## How it works

When you connect a 1Password Environment to an OpenShell gateway, 1Password transfers custody of the Environment's secrets to OpenShell for a defined time-to-live (TTL). OpenShell controls which services the agent can reach during that window.

The agent sends requests from inside the sandbox using placeholder values, so it never sees your actual secrets. OpenShell replaces the placeholders with secret values only when a request matches the active network policy and the provider’s approved host. Secret values never enter the agent process or context.

When the time window expires or if the request doesn't match, OpenShell stops replacing the placeholders, so requests that need the secret fail while the sandbox keeps running.

OpenShell governs how the agent runs, which services it can reach, and where its inference requests go. OpenShell enforces these controls outside the agent's process, so the agent can't change or get around them.

<Tip>
  **New to NVIDIA OpenShell?** [Learn how to get started. <Icon icon="arrow-up-right-from-square" />](https://docs.nvidia.com/openshell/about/installation)
</Tip>

## Step 1: Set up an Environment

Set up an Environment in 1Password to store your project secrets for a specific project or development context. If you already have an Environment you want to use, skip to [step 2](#step-2-turn-on-the-integration).

1. In the 1Password desktop app, go to **Developer** > **View Environments**.
2. Select **New environment**.
3. Enter a name for the new Environment, then select **Save**.
4. Add the variables for your project or import an existing `.env` file.

## Step 2: Turn on the integration

1. Open the 1Password desktop app.
2. Select your account or collection at the top of the sidebar, then navigate to **Settings** > **[Developer](onepassword://settings/developers)**.
3. Under Developer Integrations, select **Provision OpenShell providers**.

## Step 3: Connect the Environment to OpenShell

To connect an Environment to OpenShell:

1. In the 1Password desktop app, select **Developer** in the sidebar, then select **View Environments**.
2. Find the name of the Environment you want to use and select **View environment**.
3. Under "Connect to", select the **Connect** button next to "OpenShell provider".

You'll be prompted to configure the following:

* **Provider name**: The name you'll pass to `openshell sandbox create --provider <provider-name>`.
* Whether you want to use an existing [provider profile <Icon icon="arrow-up-right-from-square" />](https://docs.nvidia.com/openshell/dev/how-it-works/providers/profiles) or create your own:
  * **Existing profile:** Use a profile that's already been imported on your gateway, such as one for AWS or GitHub. A new gateway has no profiles until someone imports them.
  * **New profile:** 1Password creates a profile on your gateway for you. You set the host, port, and read/write permissions.
    * **Host:** The host a sandbox can make requests to. OpenShell only attaches this provider's credentials to requests for the approved host and port.
    * **Port:** The port a sandbox can reach on that host. Requests to any other port don't receive the credential.
    * **Allow writes:** Select this to allow write operations at the approved destination. If you leave it unselected, the provider allows read-only access.
* **Secrets expire**: The duration of time that OpenShell will resolve placeholders in requests from the sandbox with your secrets. After expiration, the sandbox keeps running, but OpenShell stops resolving the placeholders. To restore access, approve a new connection.

<Tip>
  The provider configuration prompt lists all required environment variables for your profile. If any variables are missing from your Environment, 1Password will alert you to add them before you can connect.
</Tip>

<Columns cols={2}>
  <div>
    <p>After you configure your provider, select **Connect**.</p>

    <p>You'll be prompted to authorize OpenShell's access to your Environment with a detailed authorization prompt that includes the provider name, variables, destinations, expiry, and your account name.</p>
  </div>

  <div>
    <Frame>
      <video loop autoPlay muted playsInline>
        <source type="video/mp4" src="https://mintcdn.com/ab-634991b8/6gXshRLCUn34EKmE/static/videos/openshell-auth-prompt.mp4?fit=max&auto=format&n=6gXshRLCUn34EKmE&q=85&s=173821624df5845111b4bf53694a440f" data-path="static/videos/openshell-auth-prompt.mp4" />

        <source type="video/webm" src="https://mintcdn.com/ab-634991b8/6gXshRLCUn34EKmE/static/videos/openshell-auth-prompt.webm?fit=max&auto=format&n=6gXshRLCUn34EKmE&q=85&s=4f5b796e60e86b046bc353fc68772343" data-path="static/videos/openshell-auth-prompt.webm" />
      </video>
    </Frame>
  </div>
</Columns>

## Step 4: Run the setup command

With the provider set up, you can now attach the provider to an OpenShell sandbox. OpenShell owns the sandbox and has custody of the credentials in your Environment for the time window you set.

1. In the 1Password desktop app, open the Environment.
2. In the "Connected to" section, select the ellipsis <Icon icon="ellipsis-v" /> to the right of "OpenShell provider" then select **Copy setup commands**.
3. Paste and run the command in your terminal. The copied command creates a sandbox with your provider attached and starts a Bash shell. For example:

   ```shell theme={null}
   openshell sandbox create --provider <provider-name> -- bash
   ```

   To start an agent, edit the command before you run it. Use `--from` to specify an image that contains the agent, and replace `bash` after `--` with the agent’s command. For example:

   ```shell theme={null}
   openshell sandbox create \
       --from <image-with-claude-installed> \
       --provider <provider-name> \
       -- claude
   ```

   If your agent needs another credential, such as an API key, you can set up another OpenShell provider from a 1Password Environment. Add a `--provider` flag for each provider you want to attach.

<Tip>
  Make sure your sandbox policy permits the network access your agent needs. If the agent will write to a service, such as pushing to GitHub, check that the credential in its attached provider has the required permissions too. See [OpenShell’s policy documentation <Icon icon="arrow-up-right-from-square" />](https://docs.nvidia.com/openshell/dev/how-it-works/policies/manage-policies/) to learn more about policy changes.
</Tip>

## Step 5: Test the connection

Give your agent a task that needs secrets from your Environment. For example, if you set up a GitHub provider, ask the agent to write a script and push it to your repository. Replace `<org>` and `<repo>` with your GitHub username or organization and repository name.

```
Write a `hello_world.py` script, commit it to a new branch called `test-openshell`, and push the branch to `https://github.com/<org>/<repo>`.
```

The agent sends the request with placeholders, then OpenShell replaces them with your secrets before forwarding it to GitHub.

To confirm the gateway allowed the request, run `openshell term` in a terminal outside the sandbox and look for allowed requests to `github.com` or `api.github.com`.

The push only works if the provider allows writes and the sandbox's network policy permits pushes to your repository. If the push is denied, check the deny reason in `openshell term`.

## Manage your workflows

### Reconnect an Environment to OpenShell

To reconnect an expired Environment to OpenShell:

1. In the 1Password desktop app, select **Developer** in the sidebar, then select **View Environments**.
2. Find the name of the Environment you want to reconnect and select the ellipsis <Icon icon="ellipsis-v" /> > **Send again**.

### Remove an Environment from OpenShell

To remove an Environment from OpenShell:

1. In the 1Password desktop app, select **Developer** in the sidebar, then select **View Environments**.
2. Find the name of the Environment you want to remove and select the ellipsis <Icon icon="ellipsis-v" /> > **Delete workflow**.

## Troubleshooting

### If you don't see the option to connect to OpenShell

Make sure you're using the [latest nightly version of the 1Password desktop app](https://support.1password.com/betas/#install-a-prerelease-version-of-the-1password-app). To check your current version:

1. Open the 1Password desktop app.
2. Select your account or collection at the top of the sidebar, then navigate to **Settings** > **About**.

You may need to restart the app to download the latest nightly release.

### If you can't connect an Environment to OpenShell

Make sure you turned on **Provision OpenShell providers** in **Settings** > **Developer**.

If 1Password alerts you that variables are missing, add the required variables for your provider profile to the Environment, then try again.

### If requests to a service fail

OpenShell only replaces placeholders for the host and port in your provider profile. Requests to other hosts go out with the placeholder, so the service rejects them. To use another service, connect the Environment with a profile for that host.

### If requests fail after previously working

Your secrets may have expired. After the time you set, the gateway stops replacing placeholders, so requests that need your secrets fail. To keep working, [reconnect the Environment](#reconnect-an-environment-to-openshell).

## Learn more

* [1Password Environments](/environments)
* [1Password Environments MCP Server](/environments/mcp-server)
* [Autofill credentials in browser-based agents with 1Password Agentic Autofill](/agentic-autofill)
* [Workflow: Secure AI access](/get-started/secure-ai-access)


## Related topics

- [Secure secrets for AI agents and tools](/get-started/secure-ai-access.md)
- [Security for AI](/security-for-ai.md)
- [Use 1Password Credential Broker to access secrets in custom workflows at runtime (public beta)](/brokered-access/custom-workflow.md)