Skip to main content
This guide walks you through running a complete audit on your web application from scratch.

​
1. Install and authenticate

If you haven’t already, install the CLI and log in: 
npx qaos auth --ui
See Installation and Authentication for detailed instructions.

​
2. Create a config file

Create a file named qaos-config.json in your project directory:
qaos-config.json
{
  "name": "My First Audit",
  "projectId": "your-project-id-here",
  "tasks": [
    {
      "id": "1",
      "description": "Navigate to the login page and attempt to log in",
      "startUrl": "https://your-app.com/login",
      "subAgents": ["security", "uiux"]
    },
    {
      "id": "2",
      "description": "Browse the main dashboard as an authenticated user",
      "startUrl": "https://your-app.com/dashboard",
      "subAgents": ["security", "uiux"]
    }
  ]
}
Replace your-project-id-here with a project ID from the QAOS Dashboard, and update the URLs to point to your application.
Not sure how to structure your config? The QAOS Dashboard has a visual config builder that generates the JSON for you. See Using the UI.

​
3. Start the run

npx qaos run --config ./qaos-config.json
The CLI will:
  1. Connect to the QAOS server
  2. Launch a headless browser
  3. Navigate to each task’s start URL
  4. Run the security and quality agents in parallel
  5. Stream findings to your terminal in real time
You’ll see output like: 
✓ Connected to QAOS server
✓ Run started: run_abc123

Task 1/2 · Login page
  ⟳ Navigating to https://your-app.com/login
  ⟳ Security agent evaluating...
  ✗ [CRITICAL] session-id-in-url — Session token exposed in URL parameter
  ✓ Quality agent: no issues found

Task 2/2 · Dashboard
  ⟳ Navigating to https://your-app.com/dashboard
  ✓ Security agent: no issues found
  ✗ [MEDIUM]   missing-form-labels — 2 input fields without labels

Run complete · 2 issues found
View full report: https://qaos.machdel.com/reports/run_abc123

​
4. View the report

Open the report URL printed at the end of the run, or navigate to Reports in the QAOS Dashboard. The report includes:
  • Every detected issue with severity, description, and location
  • Screenshots and reproduction context
  • Fix recommendations for each issue

​
Run in headed mode

To watch the browser as it runs — useful for debugging your config or understanding what the agent is doing: 
npx qaos run --config ./qaos-config.json --headed
A browser window will open and you can observe every navigation, click, and form interaction in real time.

​
Next steps

Configure a run

Learn all configuration options and how to write effective task descriptions.

Issue reference

Understand every issue type QAOS detects and how to fix them.