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

# Quickstart

> Start your first QAOS security and UI/UX audit in under five minutes.

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

***

## 1. Create an account and project

Before anything else, [sign up for a QAOS account](https://qaos.machdel.com/login) and create a project from the [QAOS Dashboard](https://qaos.machdel.com). You'll need your **project ID** in the next steps.

***

## 2. Install and authenticate

If you haven't already, install the CLI and log in:

```bash theme={null}
npx qaos auth --ui
```

See [Installation](/getting-started/installation) and [Authentication](/getting-started/authentication) for detailed instructions.

***

## 3. Create a config file

Create a file named `qaos-config.json` in your project directory. With **QAOS Mode**, the agent crawls your entire site automatically — no need to define individual tasks:

```json qaos-config.json theme={null}
{
  "name": "My First Audit",
  "projectId": "your-project-id-here",
  "qaosMode": true,
  "qaosConfig": {
    "startUrl": "https://your-app.com",
    "subAgents": ["security", "uiux"]
  }
}
```

Replace `your-project-id-here` with a project ID from the [QAOS Dashboard](https://qaos.machdel.com), and set `startUrl` to your application's home page.

<Tip>
  Need more control over which specific pages to test? You can use Guided Mode instead of QAOS Mode. See [Configuration Overview](/configuration/overview).
</Tip>

***

## 4. Start the run

```bash theme={null}
npx qaos run --config ./qaos-config.json
```

The CLI will:

1. Connect to the QAOS server
2. Launch a headless browser
3. Start crawling from the provided `startUrl`
4. Autonomously discover and navigate pages across your site
5. Run the security and UI/UX agents on each page it visits
6. Stream findings to your terminal in real time

<Tip>
  Add `--headed` to watch the browser in real time as it navigates your app:

  ```bash theme={null}
  npx qaos run --config ./qaos-config.json --headed
  ```
</Tip>

<Warning>
  **Agent limitations:** The QAOS agent operates as an automated browser and has some inherent constraints:

  * **File uploads** are not supported. Pages that require file input will be skipped.
  * **Third-party authentication** (e.g. "Sign in with Google") cannot be completed unless it is mocked in your environment. Use a standard username/password login, or set up a mock OAuth provider, so the agent can authenticate.
  * **Bot detection** may flag the agent and block navigation. Disable any bot protection (WAF rules, rate limiting, browser fingerprinting) in your test environment before running.
  * **CAPTCHA / bot challenges** will block the agent. Disable them in your test environment or use an allowlisted IP.
</Warning>

## 5. View the report

Open the report URL printed at the end of the run, or navigate to **Reports** in the [QAOS Dashboard](https://qaos.machdel.com). The report includes:

* Every detected issue with severity, description, and location
* Reproduction context
* Fix recommendations for each issue

***

## Next steps

<CardGroup cols={2}>
  <Card title="Configure a run" icon="sliders" href="/configuration/overview">
    Learn all configuration options and how to write effective task descriptions.
  </Card>

  <Card title="Issue reference" icon="triangle-exclamation" href="/issues/overview">
    Understand every issue type QAOS detects and how to fix them.
  </Card>
</CardGroup>