Skip to main content

Quick Start

This is a quick guide to get the Waterwheel agent running on your local machine and execute a sample QA task. The steps below cover macOS / Linux, Windows (PowerShell), and Windows (CMD). Use the tabs to pick your shell.

Once you're inside the container, the OS no longer matters

Only the host-side setup steps (setting environment variables and docker run) differ between operating systems. Commands such as config-agent, manage-test-files, run-qa, and check-test-result are run through docker exec and are identical on every platform, so those steps are shown as a single code block.

What Is Shipped​

The Waterwheel agent is shipped as a Docker image — a self-contained, read-only package that bundles the agent together with everything it needs to run (runtime, browser, and dependencies). Shipping as an image gives you:

  • Platform independent — the same image runs identically on macOS, Linux, and Windows, so there is nothing OS-specific to install or configure.
  • Easy integration — a single docker run command pulls and starts the agent, and the image runs on any container platform (local Docker, CI runners, or container services like Kubernetes), so it slots into automated QA pipelines without environment-specific setup.
  • Your data stays in your environment — the agent runs entirely within your own infrastructure, and your test files and results never leave it: there is no Waterwheel-hosted backend. The only data sent externally is to the LLM provider you configure, and with a self-hosted Ollama model even that stays inside your environment.

Prerequisites​

Docker Desktop Application​

The Waterwheel agent is shipped as a Docker image, so you need a container runtime to pull and run it. Install Docker Desktop for your machine from docker.com/get-started and make sure it is running before you continue.

AI API Key​

The agent must connect to an LLM to perform QA tasks, so you need to provide your own AI API key. Currently supported AI providers include Anthropic, OpenAI, Gemini, DeepSeek and Ollma hosted Gemma 4.

Gemma 4 Support

For simple QA tasks, you can use Ollama-hosted Gemma 4. When using Gemma 4, you can use any non-empty text as the API key.

About your API key's safety

The agent uses your key the same way any standard LLM client does — as the credential on requests to the provider you configure. It is read from an environment variable inside your own container and sent only to that provider's API; there is no Waterwheel-hosted service that receives it. You stay in full control: use a scoped, spend-limited key, monitor the container's outbound traffic, and rotate or revoke the key at any time. If you simply want to inspect what's inside the image before committing a real key, you can start the container with any non-empty text as the API key and look around first.

1. Set Your API Key​

Export your AI provider API key into the current shell session. The optional second line silences Docker's CLI hint messages.

# Required: your AI provider API key
export AI_API_KEY=your_api_key_here

# Optional: silence Docker CLI hint messages
export DOCKER_CLI_HINTS=false
Session Scope

These variables live only in the terminal window where you set them. Run the docker run command in step 2 from the same terminal so the key is available to the container.

2. Install the Waterwheel Container​

This pulls the image (on first run) and starts the agent in the background. It mounts two folders from your current directory: import, a staging area for any files you want to move into the container (test tasks, preset flow files, and so on), and outputs where results and logs are written.

docker run -d --name waterwheel-agent \
  -v "$(pwd)/import":/agent/import \
  -v "$(pwd)/outputs":/agent/outputs \
  -e AI_API_KEY \
  taojdcn/duotail-waterwheel:1.3.0
Volume mounts on Windows

Docker Desktop's WSL 2 backend handles ${PWD} (PowerShell) and %cd% (CMD) automatically. If a volume fails to mount, confirm that your drive is shared under Docker Desktop → Settings → Resources → File sharing.

3. Configure the Agent​

Launch the interactive configuration script. It walks you through choosing an AI provider mode.

docker exec -it waterwheel-agent config-agent
The AI provider is locked once set

After you save a provider mode, switching to a different provider (for example Anthropic → DeepSeek) requires creating a new container. You can still switch between modes of the same provider at any time. See the Provider Configuration Guide for recommended provider settings.

4. Add a Sample Test​

Download the sample test into the import folder next to where you ran docker run:

test-wikipedia-english.md

This sample verifies that clicking the English language link on wikipedia.org navigates to the English welcome page.

Because import is mounted into the container, the file is available at /agent/import immediately. Use manage-test-files add to move it into the agent's tasks folder:

docker exec -it waterwheel-agent manage-test-files add /agent/import/test-wikipedia-english.md

Then confirm the agent sees it:

docker exec -it waterwheel-agent manage-test-files list

The list command should show test-wikipedia-english.md.

Managing tasks later

Drop more files into your import folder on the host, then move them into the container with the management commands. Use manage-test-files add for .md task files, and preset-context flow to import a flow file. You can also remove tasks with manage-test-files delete and manage-test-files clear. See the Usage guide for the full command reference.

5. Verify Your Configuration​

Run a dry run first to confirm everything is wired up correctly without consuming tokens.

docker exec -it waterwheel-agent run-qa --dry-run

6. Run Your QA Tasks​

When the dry run looks good, execute the tests in the tasks directory, which contains the sample test from step 4.

docker exec -it waterwheel-agent run-qa

7. Check the Results​

Print the contents of the latest test results.

docker exec -it waterwheel-agent check-test-result
Investigating a failure

For a detailed diagnostic report of the first failed test — including the test steps, agent log, and context — use:

docker exec -it waterwheel-agent get-failure-detail

Uninstallation​

If you need to change your AI provider, uninstall the agent and reconfigure it from step 1. Your import and outputs folders on the host are untouched.

docker rm -f waterwheel-agent

Next Steps​

Please read Usage and Manage Test Tasks to learn how to use the agent to test your website.