Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.qaos.machdel.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Basic usage

With a config file ready and the CLI authenticated, start a run: 
npx qaos run --config ./qaos-config.json
The CLI connects to the QAOS server, launches a headless browser, and begins executing tasks. Progress is streamed to your terminal in real time.

​
Command options

npx qaos run [options]
OptionAliasDescriptionDefault
--config <path>-cPath to the config JSON file./qaos-config.json
--headed-hRun with a visible browser windowHeadless

​
Default config lookup

If no --config flag is given, QAOS looks for qaos-config.json in the current working directory: 
npx qaos run  # uses ./qaos-config.json

​
Headed mode

Use --headed (or -h) to open a visible browser window during the run. This is useful for:
  • Debugging task descriptions that aren’t producing expected behavior
  • Watching the agent navigate your application
  • Understanding how the agent interprets your pages
npx qaos run --config ./qaos-config.json --headed
Headed mode may be slightly slower than headless mode. Use headless for production CI pipelines.

​
What happens during a run

1

Connection

The CLI connects to the QAOS server over WebSocket and sends your config to initiate the run. A run ID is assigned and printed.
2

Task execution

Tasks execute sequentially. For each task:
  • The browser navigates to startUrl
  • The agent analyzes the page (DOM, screenshots, network headers, cookies, console logs)
  • Subtasks are generated for interactive tests (e.g., attempting login with weak passwords)
  • Issues are detected and reported in real time
3

Agent evaluation

At each page, the selected subagents evaluate the page against their full issue catalog, using a combination of deterministic checks (fast, code-based) and LLM evaluation (deeper, context-aware).
4

Completion

Once all tasks finish, the CLI prints a summary of detected issues and a link to the full report in the dashboard.

​
Real-time output

While the run is in progress, the CLI streams findings to your terminal as they are detected, and prints a summary with a link to the full report once the run completes.

​
Running in CI/CD

QAOS works well in CI pipelines. Use API token authentication and a pre-committed config file:
GitHub Actions example
- name: Run QAOS security audit
  run: |
    npx qaos auth --api ${{ secrets.QAOS_API_TOKEN }}
    npx qaos run --config ./qaos-config.json
  env:
    QAOS_API_TOKEN: ${{ secrets.QAOS_API_TOKEN }}
The CLI exits with code 0 on success and a non-zero code if the run fails or the server is unreachable.

​
Known limitations

The QAOS agent runs as an automated browser and cannot perform every action a human user can:
LimitationDetails
File uploadsPages with file input fields are skipped. The agent cannot select or upload files from disk.
Third-party OAuth”Sign in with Google / GitHub / etc.” flows cannot be completed. Use a native username/password login or configure a mock OAuth provider in your test environment so the agent can authenticate.
CAPTCHA / bot challengesHard CAPTCHAs will block the agent. Disable them for your test environment or use an allowlisted IP.
Bot detectionWAF rules, rate limiting, and browser fingerprinting may identify the agent as a bot and block navigation. Disable bot protection in your test environment before running.

​
Troubleshooting

Your token may have expired or been revoked. Re-authenticate:
npx qaos auth --api <your-token>
# or
npx qaos auth --ui
Check the path you provided:
ls ./qaos-config.json      # verify it exists
npx qaos run --config ./path/to/config.json
QAOS requires Playwright browser binaries to be installed on your machine. Install them once before your first run:
npx playwright install chromium
If the binaries are missing, QAOS will show an error message asking you to run the above command. After installing, simply retry your run.
If your application loads slowly, consider adding descriptive context in your task config to help the agent understand the expected behavior. Each task has a generous timeout, but very slow pages may occasionally be skipped.