Providers Setup

Configure a Bitwarden Secrets Manager access token and organization ID:

export BITWARDEN_ACCESS_TOKEN="your-access-token"    # or ACCESS_TOKEN
export BITWARDEN_ORGANIZATION_ID="your-organization-id"

You can also set the organization ID in your kuba.yaml via the project field when using the bitwarden provider; that value is treated as the Bitwarden organization ID.

To use a self-hosted Bitwarden instance, configure the API and identity URLs:

export BITWARDEN_API_URL="https://your-bitwarden.example.com/api"
export BITWARDEN_IDENTITY_URL="https://your-bitwarden.example.com/identity"

Optional: if you want the Bitwarden SDK to reuse its own state between Kuba runs (for example, to avoid re-initializing some internal session data), you can point it at a state file. The SDK will create and maintain this file itself:

export BITWARDEN_STATE_FILE="$HOME/.local/share/kuba/bitwarden_state.json"

Treat this file as sensitive: keep it outside version control and in a user-scoped data directory (for example, ~/.local/share/kuba on Linux/macOS or %LOCALAPPDATA%\kuba on Windows). You still need a valid Bitwarden access token; the state file complements it rather than replacing it.

3. Configuration Example

In your kuba.yaml, use the bitwarden provider. The secret-key values must be Bitwarden secret IDs:

default:
  provider: bitwarden
  # Optional: if omitted, BITWARDEN_ORGANIZATION_ID must be set
  project: "your-bitwarden-organization-id"
  env:
    DATABASE_URL:
      secret-key: "bitwarden-secret-id-for-database-url"
    API_KEY:
      secret-key: "bitwarden-secret-id-for-api-key"
    SOME_HARD_CODED_ENV:
      value: "hard-coded-value"

Note: Bitwarden support in Kuba currently only supports secret-key mappings (by secret ID). secret-path mappings are not available for the bitwarden provider.

2. IAM Permissions

Ensure your AWS credentials have the secretsmanager:GetSecretValue permission:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "secretsmanager:GetSecretValue",
      "Resource": "arn:aws:secretsmanager:region:account:secret:secret-name-*"
    }
  ]
}

3. Configuration Example

default:
  provider: aws
  env:
    DATABASE_URL:
      secret-key: "database-connection-string"
    API_KEY:
      secret-key: "external-api-key"

2. Key Vault Permissions

Ensure your Azure credentials have the Get and List permissions for secrets in your Key Vault.

3. Configuration Example

default:
  provider: azure
  env:
    DATABASE_URL:
      secret-key: "database-connection-string"
    API_KEY:
      secret-key: "external-api-key"

1. Setup

Make sure you have an OpenBao server running and accessible.

Set up authentication using environment variables:

export OPENBAO_ADDR="http://localhost:8200"  # Required: OpenBao server address
export OPENBAO_TOKEN="your-openbao-token"    # Optional: Authentication token
export OPENBAO_NAMESPACE="your-namespace"     # Optional: Namespace (if using enterprise features)

3. Permissions

Ensure your OpenBao token has read permissions for the secrets you want to access.

4. Configuration Example

default:
  provider: openbao
  env:
    DATABASE_URL:
      secret-key: "secret/database-url"
    API_KEY:
      secret-key: "secret/api-key"

Note: OpenBao secrets are stored as key-value pairs. If a secret contains multiple keys, Kuba will return the first string value it finds.

2. Configuration Example

default:
  provider: local
  env:
    LOG_ENV:
      value: "local"
    LOG_LEVEL:
      value: "debug"

Common Issues

Debug Mode

Enable debug mode to see detailed information about authentication and API calls:

kuba run --debug -- echo "Testing connection"