Skip to main content

​
Overview

OpenHands provides a secrets manager that allows you to securely store and manage sensitive information that can be accessed by the agent during runtime, such as API keys. These secrets are automatically exported as environment variables in the agent’s runtime environment.

​
Accessing the Secrets Manager

Navigate to the Settings > Secrets page. Here, you’ll see a list of all your existing custom secrets.

​
Adding a New Secret

  1. Click Add a new secret.
  2. Fill in the following fields:
    • Name: A unique identifier for your secret (e.g., AWS_ACCESS_KEY). This will be the environment variable name.
    • Value: The sensitive information you want to store.
    • Description (optional): A brief description of what the secret is used for, which is also provided to the agent.
  3. Click Add secret to save.

​
Editing a Secret

  1. Click the Edit button next to the secret you want to modify.
  2. Update its name, value, or description.
  3. Save the changes.
For security, the existing value is not displayed. Enter a replacement value when you need to overwrite it.

​
Deleting a Secret

  1. Click the Delete button next to the secret you want to remove.
  2. Select Confirm to delete the secret.

​
Using Secrets in the Agent

  • All custom secrets are automatically exported as environment variables in the agent’s runtime environment.
  • You can access them in your code using standard environment variable access methods. For example, if you create a secret named OPENAI_API_KEY, you can access it in your code as process.env.OPENAI_API_KEY in JavaScript or os.environ['OPENAI_API_KEY'] in Python.

​
Agent-Requested Secrets

Secrets saved in Settings > Secrets reach conversations that start after the save. During a conversation, the agent can also ask for a credential it needs for the current task. The agent uses its request_secret tool to ask for a secret. The request appears as a The agent needs a secret card inline in the chat, immediately after the tool call, with the agent’s reason for the request and a prefilled name. The request does not block the conversation: the agent can keep working on anything that does not need the secret while the card is pending, and you can answer whenever you are ready. The card stays in place if you reload the conversation. When you fill in the value and select Add secret:
  • The secret is saved to your secrets and attached to the running conversation, so the agent can use it right away.
  • The agent receives only a status result. The secret value never appears in the chat, in the agent’s events, or in the tool arguments.
  • If you select Cancel, the agent is told the request was not saved, and no secret is created.
If the requested name is already saved, Agent Canvas attaches the existing secret to the running conversation and does not show a card. The agent can request a secret only on a local backend. On other backends, use Settings > Secrets to save the credential and start a new conversation.

​
Configuring Secrets for Common Git Providers

​
GitHub Setup

OpenHands automatically exports a GITHUB_TOKEN to the shell environment if provided:
  1. Generate a Personal Access Token (PAT):
  • On GitHub, go to Settings > Developer Settings > Personal Access Tokens.
  • Tokens (classic)
    • Required scopes:
      • repo (Full control of private repositories)
  • Fine-grained tokens
    • All Repositories (You can select specific repositories, but this will impact what returns in repo search)
    • Minimal Permissions (Select Meta Data = Read-only read for search, Pull Requests = Read and Write and Content = Read and Write for branch creation)
  1. Enter token in OpenHands:
  • Navigate to the Settings > Integrations page.
  • Paste your token in the GitHub Token field.
  • Click Save Changes to apply the changes.
If you’re working with organizational repositories, additional setup may be required:
  1. Check organization requirements:
  • Organization admins may enforce specific token policies.
  • Some organizations require tokens to be created with SSO enabled.
  • Review your organization’s token policy settings.
  1. Verify organization access:
  • Go to your token settings on GitHub.
  • Look for the organization under Organization access.
  • If required, click Enable SSO next to your organization.
  • Complete the SSO authorization process.
  • Token Not Recognized:
    • Check that the token hasn’t expired.
    • Verify the token has the required scopes.
    • Try regenerating the token.
  • Organization Access Denied:
    • Check if SSO is required but not enabled.
    • Verify organization membership.
    • Contact organization admin if token policies are blocking access.

​
GitLab Setup

OpenHands automatically exports a GITLAB_TOKEN to the shell environment if provided:
  1. Generate a Personal Access Token (PAT):
  • On GitLab, go to User Settings > Access Tokens.
  • Create a new token with the following scopes:
    • api (API access)
    • read_user (Read user information)
    • read_repository (Read repository)
    • write_repository (Write repository)
  • Set an expiration date or leave it blank for a non-expiring token.
  1. Enter token in OpenHands:
  • Navigate to the Settings > Integrations page.
  • Paste your token in the GitLab Token field.
  • Click Save Changes to apply the changes.
  1. (Optional): Restrict agent permissions
  • Create another PAT using Step 1 and exclude api scope .
  • In the Settings > Secrets page, create a new secret GITLAB_TOKEN and paste your lower scope token.
  • OpenHands will use the higher scope token, and the agent will use the lower scope token.
  • Token Not Recognized:
    • Check that the token hasn’t expired.
    • Verify the token has the required scopes.
  • Access Denied:
    • Verify project access permissions.
    • Check if the token has the necessary scopes.
    • For group/organization repositories, ensure you have proper access.

​
BitBucket Setup

  1. Generate an App password:
    • On Bitbucket, go to Account Settings > App Password.
    • Create a new password with the following scopes:
      • account: read
      • repository: write
      • pull requests: write
      • issues: write
    • App passwords are non-expiring token. OpenHands will migrate to using API tokens in the future.
  2. Enter token in OpenHands:
  • Navigate to the Settings > Integrations page.
  • Paste your token in the BitBucket Token field.
  • Click Save Changes to apply the changes.
  • Token Not Recognized:
    • Check that the token hasn’t expired.
    • Verify the token has the required scopes.