> ## 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.

# Using the UI Config Builder

> Generate a QAOS config file using the visual builder in the dashboard — no JSON editing required.

The QAOS dashboard includes a guided config builder that generates a valid `qaos-config.json` for you. This is the fastest way to set up a new run, especially if you're not familiar with the JSON format.

***

## Accessing the builder

1. Log in to the [QAOS Dashboard](https://qaos.machdel.com)
2. Navigate to **Projects** and open or create a project
3. Click **New Run → Configure with UI**

***

## Step 1 — Name your run

Enter a descriptive name for this run. This name appears in your run history and reports, so make it identifiable:

```
Production audit — March 2025
Login flow security check
Post-deploy accessibility review
```

***

## Step 2 — Choose a mode

Select how you want the agent to explore your application:

* **Guided Mode** — you define each task manually with a description and start URL. Best when you have specific flows to test.
* **QAOS Mode** — the agent starts at a single URL and autonomously crawls your entire site, discovering pages on its own. Best for broad audits with minimal setup.

***

## Step 2a — QAOS Mode configuration

If you selected **QAOS Mode**, fill in:

* **Website origin** — the root of the site the agent begins crawling from (e.g. `https://your-app.com` or `C:/my-site`)
* **Subpath** — the starting page within that origin (e.g. `/` or `/index.html`). Leave blank to start from the root.
* **Agents to run** — toggle **Security** and/or **UI/UX**
* **Max pages** *(optional)* — limit how many pages the agent visits
* **Max depth** *(optional)* — limit how many link levels deep the agent follows from the start URL

The agent discovers and audits pages on its own — no tasks required. Skip to [Step 3](#step-3--review-and-export).

***

## Step 2b — Add tasks (Guided Mode)

Click **Add Task** to define each test scenario.

For each task, fill in:

<Steps>
  <Step title="Task description">
    Describe what the agent should do in natural language. Be specific about the user flow and what you want tested.

    **Example:** `"Navigate to the checkout page, add an item, and proceed through the payment flow"`
  </Step>

  <Step title="Website origin and subpath">
    Enter where the agent should begin this task using two fields:

    * **Website origin** — the root of the site (e.g. `https://your-app.com` or `C:/my-site`). Shared across all tasks; setting it on one task sets it for the whole run.
    * **Subpath** — the page-specific path within that origin (e.g. `/shop/cart` or `/index.html`).

    The full start URL is constructed by combining both: `https://your-app.com/shop/cart`.
  </Step>

  <Step title="Agents to run">
    Toggle the **Security** and/or **UI/UX** agent for this task. Both are enabled by default.

    * **Security** — checks for vulnerabilities, access control issues, weak cryptography, etc.
    * **UI/UX** — checks for accessibility violations, UX issues, navigation problems, etc.

    Leaving both unchecked is valid — the agent will still attempt to complete the task, but will not run any issue evaluations. This is primarily useful for verifying that a flow can be completed end-to-end (the task fails if the agent cannot finish it). It can also be used to set up state (e.g. log in) before a subsequent task that does run evaluations.

    <Warning>
      If you select an agent but have ignored **all** of its issues in the **Ignored issues** section, saving or downloading the config will be blocked. Either un-ignore at least one issue for that agent or remove it from the task.
    </Warning>
  </Step>
</Steps>

Repeat for each distinct area of your application you want to test.

***

## Step 3 — Review and export

Once you've added all tasks, click **Preview JSON** to see the generated config file. You can:

* **Copy to clipboard** — paste it into a file on your machine
* **Download** — save it directly as `qaos-config.json`

***

## Editing the generated config

The exported JSON is a standard QAOS config file. You can edit it freely — add more tasks, adjust descriptions, change agent selections, or add environment file references.

See the [JSON Reference](/configuration/json-reference) for a complete field description.

***

## Tips for good configs

<Tip>
  **Cover the full user journey.** Create one task per major feature area: authentication, user profile, data listings, admin panels, checkout flows, etc.
</Tip>

<Tip>
  **Include authentication context.** If your application requires login, add an authentication task first (e.g., "Log in with [admin@example.com](mailto:admin@example.com) / password123") before tasks that test authenticated pages.
</Tip>

<Warning>
  **Only test applications you own or have permission to test.** See [Terms of Use](/legal/terms-of-use) for the full policy.
</Warning>