Environments

Environments define the target URLs, credentials, and other configuration needed to execute a QA plan. Environment files are stored locally and never sent to the server, ensuring sensitive data stays on your machine.

File Location

Environment files are stored at:

.aqua/environments/<name>.json

Each file represents a named environment (e.g., local.json, staging.json, production.json). We recommend committing the .aqua/ directory to your repository so that environment configurations are shared across your team. Sensitive values are safe to commit when using secret types that reference external sources (env, op, aws_sm, etc.) — only the reference is stored in the file, not the actual secret.

File Schema

A complete environment file has the following structure:

{
  "notes": "Markdown notes about the environment",
  "variables": {
    "api_base_url": "http://localhost:8000",
    "web_base_url": "http://localhost:3000",
    ...
  },
  "secrets": {
    "api_key": { "type": "literal", "value": "dev-key-123" },
    "auth_token": { "type": "env", "value": "STAGING_AUTH_TOKEN" },
    "db_password": { "type": "op", "value": "op://Development/staging-db/password" },
    ...
  },
  "secret_providers": {
    "aws_sm": { "region": "ap-northeast-1", "profile": "staging" },
    "gcp_sm": { "project": "my-project-123" },
    "hcv": { "address": "https://vault.example.com:8200" }
  },
  "proxy": {
    "server": "http://proxy.corp.com:3128",
    "bypass": "localhost,.internal.com",
    "username": { "type": "literal", "value": "user" },
    "password": { "type": "env", "value": "PROXY_PASSWORD" },
    "ca_cert_path": "/path/to/ca.pem",
    "reject_unauthorized": false
  }
}

All sections except variables are optional.

Variables

The variables object contains plain key-value pairs. You define variable names to match what your QA plan references — any key name can be used. Variables are substituted into plan templates using {{variable_name}} syntax.

For example, if your QA plan has a step with the URL {{api_base_url}}/users, define api_base_url in your environment file to provide the value.

Two variable names are used by convention:

Variable	Purpose
api_base_url	Base URL for HTTP API requests.
web_base_url	Base URL for browser-based tests.

Variable Priority

When the same variable is defined in multiple places, the following priority order applies (highest wins):

1. Execution overrides — Values passed at execution time.
2. Environment file — Values from .aqua/environments/<name>.json.
3. Plan defaults — Default values defined in the QAPlanVersion.

Secrets

Secrets work like variables but hold sensitive values such as API keys, auth tokens, and passwords. You define secret names to match what your QA plan references — just like variables, any key name can be used. The difference is that each secret specifies a type that determines how the value is resolved, and resolved values are always masked before being sent to the server.

Once resolved, secrets are merged into the same variable namespace as plain variables and can be referenced in plan templates with the same {{secret_name}} syntax.

Secret Types

Type	Description	Example
literal	The value is used directly as written.	{ "type": "literal", "value": "dev-key-123" }
env	The value is read from an OS environment variable.	{ "type": "env", "value": "STAGING_AUTH_TOKEN" }
op	The value is fetched from 1Password CLI.	{ "type": "op", "value": "op://vault/item/field" }
aws_sm	The value is fetched from AWS Secrets Manager.	{ "type": "aws_sm", "value": "staging/db-creds" }
gcp_sm	The value is fetched from GCP Secret Manager.	{ "type": "gcp_sm", "value": "api-key" }
hcv	The value is fetched from HashiCorp Vault.	{ "type": "hcv", "value": "myapp/keys" }

Cloud Secret Manager Options

The aws_sm, gcp_sm, and hcv types support additional fields for fine-grained control:

AWS Secrets Manager (aws_sm)

Field	Description
value	Secret name or ARN.
region	(optional) AWS region. Overrides the provider-level setting.
json_key	(optional) Extract a specific key from a JSON-formatted secret.

GCP Secret Manager (gcp_sm)

Field	Description
value	Secret name.
project	(optional) GCP project ID. Overrides the provider-level setting.
version	(optional) Secret version. Defaults to latest.
json_key	(optional) Extract a specific key from a JSON-formatted secret.

HashiCorp Vault (hcv)

Field	Description
value	Secret path.
field	(optional) Extract a specific field from the secret.
mount	(optional) KV mount point. Defaults to secret.

Secret Providers

The secret_providers section sets default configuration for each external secret type. Entry-level fields override provider-level fields.

{
  "secret_providers": {
    "aws_sm": {
      "region": "ap-northeast-1",
      "profile": "staging"
    },
    "gcp_sm": {
      "project": "my-project-123"
    },
    "hcv": {
      "address": "https://vault.example.com:8200",
      "namespace": "staging"
    }
  }
}

This avoids repeating the same region or project in every secret entry. For example, if all your AWS secrets are in ap-northeast-1, set the region once in secret_providers.aws_sm and omit it from individual entries.

Lazy Resolution

Only secrets that are actually referenced in the current plan are resolved. If your environment file defines ten secrets but the plan only uses two, only those two are looked up. This avoids unnecessary calls to external secret managers and prevents errors from unused secrets that may not be configured.

Secret Masking

Before any data is sent to the aqua server, all resolved secret values are replaced with ***. This ensures that sensitive information never leaves your machine, even when execution results are recorded on the server. Masking is applied across multiple layers — environment values, HTTP request/response headers, and DOM snapshots.

Secrets are never exposed to the AI agent

When you execute a QA plan through a coding agent, secrets are resolved locally on your machine by the aqua MCP server process — not by the AI agent itself. The agent only receives masked execution results and never sees raw secret values. You can safely use API keys, passwords, and tokens in your environments without concern about them being sent to the AI model.

Proxy

The optional proxy section configures an HTTP proxy for outbound requests during test execution.

Field	Description
server	Proxy server URL (e.g., http://proxy.corp.com:3128).
bypass	Comma-separated list of hosts that should bypass the proxy.
username	(optional) Proxy authentication username. Uses the same secret type format.
password	(optional) Proxy authentication password. Uses the same secret type format.
ca_cert_path	(optional) Path to a CA certificate file for target server TLS verification (e.g., self-signed certs or SSL-intercepting proxies).
proxy_ca_cert_path	(optional) Path to a CA certificate file for the proxy server itself (when the proxy uses HTTPS with a custom CA).
reject_unauthorized	(optional) Set to false to skip TLS certificate verification for both proxy and target connections.

Notes

The notes field accepts Markdown text and is intended for recording environment-specific information such as:

• Preconditions that must be met before running tests.
• Known constraints or limitations of the environment.
• Test account credentials or setup instructions.
• Links to environment-specific documentation.

Notes are stored locally with the environment file and are available to the AI agent during QA sessions to provide context about the target environment.