Configuration Files

The files under agent/instructions (mapped to /agent/instructions in the container) control how the agent behaves. They are reloaded every time run-qa is called, so you can edit them on the host and simply start the next run — no container restart needed. The most commonly tuned files are described below.

Test skills are not instruction files

User test skills live outside this folder — each in its own subfolder under agent/skills (/agent/skills in the container, repointable with SKILLS_DIR) holding a single SKILL.md. Unlike the files here, a skill body is loaded only when the agent decides it applies.

global-context.json

Static values shared across every test in the run — base URLs, tenant IDs, shared accounts, and similar constants. The values are injected into the agent's system prompt as global variables, so any test can reference them.

It is a plain JSON object and supports nested values via dotted keys.

global-context.json

{
    "TEST_URL": "https://www.wikipedia.org",
    "LOGIN_URL": "https://www.wikipedia.org/login",
    "user": {
        "username": "qa_user"
    }
}

You can edit this file directly, or manage it from inside the container with the manage-global-constants command. See Global Context for how tests consume these values.

preset-context.json

Per-run configuration with two independent, optional sections:

• data — seed values placed in the agent's context store before the first task runs. Unlike global context, these are not injected into the system prompt; the agent reads and overwrites them as tests run, which makes them useful for default credentials or feature flags a test can later change.
• flow — the execution order of your tasks and the dependencies between them. Keeping the flow here (rather than in the .md files) lets you reuse the same task files across different suites and environments.

preset-context.json

{
    "data": {
        "admin_username": "qa_user",
        "admin_password": "s3cret",
        "feature_new_checkout": true
    },
    "flow": [
        { "file": "login.md", "node": 1 },
        { "file": "checkout.md", "node": 2, "required": [1] }
    ]
}

You can edit this file directly, or manage it with the preset-context command. See Preset context and Define Test Flow for full details.

allowed-domains.yaml

The browser domain allowlist. The agent may only navigate to origins listed under allowed; if a test tries to reach any other URL, it fails immediately. This keeps test runs contained to the sites you intend to exercise.

allowed-domains.yaml

allowed:
  - https://*.wikipedia.org
  - http://host.docker.internal:8080

See URL Permissions for the matching rules and behavior.

extra-instruction.md

Free-form Markdown appended to the instructions for every test in the run. Use it for global rules that apply across all tasks.

Its most common use is testing a website hosted on your local machine. Inside the container, localhost refers to the container itself, not your host, so a locally hosted site is reached at host.docker.internal. Add a rewriting rule so the agent translates localhost URLs automatically:

extra-instruction.md

# Extra Test Instruction

## Global Rules

- **URL Rewriting:** Any URL containing `http://localhost` encountered during the
  test (in page content, emails, or links) MUST be rewritten to use
  `http://host.docker.internal` before navigating. For example,
  `http://localhost:8080/confirm-email?token=abc` becomes
  `http://host.docker.internal:8080/confirm-email?token=abc`. Never navigate to a
  `localhost` URL directly.

Make sure the corresponding host.docker.internal origin is also present in allowed-domains.yaml, otherwise the rewritten URL will be blocked.

tip

The config-agent command can generate and maintain extra-instruction.md for you when you enable Test web app on host.