Credentials

Most apps worth testing need a sign-in. Bugmole types passwords and tokens for your flows without anyone pasting them into a config file, a chat with an AI agent, or a test. A flow names a secret, and the value comes from somewhere you already trust: your own vault, an encrypted store on your machine, or Bugmole's encrypted store for cloud runs.

Name secrets in flows

A flow types a secret by name, never by value:

- tapOn: "Password"
- inputText: "{{secret.APP_PASSWORD}}"

Only inputText can use a secret. What is typed is masked in logs, results and step labels. A secret's value is also hidden from anything Bugmole reports, including what it tells an AI agent.

Where values come from

When a flow runs, Bugmole looks for each name in this order:

BUGMOLE_FLOW_SECRET_<NAME> in the environment of the machine running the flow. This is how CI jobs usually pass secrets.
The project's secrets: map in its Bugmole config, which points each name at a vault.
This machine's secure store, where bugmole secrets set NAME keeps it.

On Bugmole Cloud, the project's secrets from Settings → Sign-in for runs are used instead. See Bugmole Cloud below.

Use your own vault

Map names to references in the Bugmole config (bugmole.config.yaml or .bugmole/config.yaml). A reference only says where the value lives, so the config is safe to commit:

secrets:
  ADMIN_TOKEN: gcpsm://projects/acme-prod/secrets/qa-admin-token
  API_KEY: awssm://us-east-1/qa/app#api_key
  PIN: keychain://my-keychain-service/PIN
  CI_TOKEN: env://MY_CI_TOKEN

Reference	Source	Who can read it
`gcpsm://projects/P/secrets/S[/versions/V]`	Google Secret Manager	Whoever is signed in with `gcloud auth login` (or `GOOGLE_OAUTH_ACCESS_TOKEN`). `V` defaults to `latest`.
`awssm://REGION/SECRET_ID[#field]`	AWS Secrets Manager	`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`, or the AWS CLI's signed-in profile. `#field` reads one field of a JSON secret.
`keychain://SERVICE/ACCOUNT`	An entry you already have in this machine's keychain (macOS Keychain, or the Secret Service through `secret-tool` on Linux)	The signed-in user of this machine.
`env://VARIABLE`	An environment variable	Anything that can read this process's environment.

The bugmole CLI reads them itself, with nothing else to install. Values are read when a flow that types them runs, kept in memory only for that flow, and taken out of the environment again afterwards.

Keep a value on this machine

When a secret has no vault, keep it in this machine's secure store:

bugmole secrets set APP_PASSWORD

The value is typed without being shown, or piped in (op read … | bugmole secrets set APP_PASSWORD). It is stored for this project only and never printed. bugmole secrets delete APP_PASSWORD removes it.

The secure store is an encrypted file (AES-256-GCM) in Bugmole's data folder, readable only by you, whose one key is kept in your operating system's credential store: macOS Keychain, Windows Credential Manager, or the Linux Secret Service. It's part of the bugmole CLI, so there's nothing else to install, and its code is open source. A config can name it explicitly as local://NAME. On a Linux machine with no keyring (a CI runner, a container, a server), Bugmole keeps that key in a file next to the store instead, readable only by you, and says so the first time.

See what's missing

bugmole secrets

bugmole secrets lists every secret your flows type (in the spec folder, flows/ and .maestro/), where each one comes from, and whether this machine can supply it. It doesn't read any value, so it never prompts or reads your vault.

AI agents

Agents working through Bugmole MCP never see a value and never need one:

bugmole_secrets_status tells the agent which secrets the flows use and which are missing on this machine. When one is missing, the agent asks you to run bugmole secrets set NAME in your own terminal, or to map it to your vault. It shouldn't ask for a password in the chat.
bugmole_sign_in runs your sign-in flow with the secrets and returns a signed-in browser session the agent explores and tests with.

On Bugmole Cloud

Bugmole Cloud runners can't reach your machine, so cloud runs use the secrets under Settings → Sign-in for runs. Values are encrypted and write-only: no page or API shows them. They're released only to the worker holding a run or exploration of that project: a cloud runner, or your own bugmole serve (with the project's machine key), where a value set on that machine still wins. Each release is in the audit log.

Keep the value in your own vault

Instead of the value, save a reference: gcpsm://projects/P/secrets/S or awssm://REGION/SECRET_ID[#field]. The runner reads it from your vault for each run.

Nobody stores a key for this. Bugmole Cloud is an OpenID Connect identity provider (https://api.bugmole.com): for each run it signs a ten-minute token whose subject is project:<your project id>. Your cloud trusts that issuer once, for that subject only, and gives the run read access to the secrets you choose. Then save the setting it needs, as a secret, under Sign-in for runs.

Google Secret Manager

gcloud iam workload-identity-pools create bugmole --location=global --display-name="Bugmole Cloud"
gcloud iam workload-identity-pools providers create-oidc bugmole --location=global --workload-identity-pool=bugmole \
  --issuer-uri=https://api.bugmole.com --attribute-mapping=google.subject=assertion.sub \
  --attribute-condition="assertion.sub == 'project:YOUR_PROJECT_ID'"
gcloud secrets add-iam-policy-binding qa-password --role=roles/secretmanager.secretAccessor \
  --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/bugmole/subject/project:YOUR_PROJECT_ID"

Then set VAULT_GCP_WORKLOAD_PROVIDER to projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/bugmole/providers/bugmole. To go through a service account instead, give that account access, let the principal above impersonate it (roles/iam.workloadIdentityUser), and set VAULT_GCP_SERVICE_ACCOUNT to its email.

AWS Secrets Manager

In IAM, add an OpenID Connect identity provider: URL https://api.bugmole.com, audience sts.amazonaws.com.

Create a role that trusts it, only for your project:

{
  "Effect": "Allow",
  "Principal": { "Federated": "arn:aws:iam::ACCOUNT:oidc-provider/api.bugmole.com" },
  "Action": "sts:AssumeRoleWithWebIdentity",
  "Condition": { "StringEquals": { "api.bugmole.com:aud": "sts.amazonaws.com", "api.bugmole.com:sub": "project:YOUR_PROJECT_ID" } }
}

Allow the role only secretsmanager:GetSecretValue on the secrets your flows use, and set VAULT_AWS_ROLE_ARN to its ARN.

VAULT_ settings are only used to reach your vault and are never given to a flow. Stored cloud keys aren't accepted. local://, keychain:// and env:// references work only on your own machine.