Quickstart
Find your first bug in 10 minutes.
Find your first bug in 10 minutes. This guide takes you from a blank machine to your first test run, no selectors, no code, just plain language. Four steps: download AskUI Desktop, sign in, walk the onboarding wizard, and run the template's example test on your own machine.
What you need
A Windows or macOS machine. No prior automation experience required.
Step 1: Download AskUI Desktop (2 min)
Grab the installer for your platform and run it. It's self-contained, no extra runtimes needed.
Run the .exe and follow the guided setup.
Open the .dmg and drag AskUI Desktop into Applications. You'll grant
screen and input permissions during the onboarding wizard in Step 3.
Always the latest
These links always give you the newest release. The Releases page lists every installer, and they're also on your AskUI Hub account page.
Step 2: Sign up or log in (2 min)
Launch AskUI Desktop and sign in with your AskUI account.
New to AskUI? Click Sign up to create an account with your work email, accept the terms, and verify your email from the link we send. Accounts and billing live in the AskUI Hub.
Already have an account? Click Log in and authenticate in your browser. The same login works across Desktop, the CLI, and the Hub.
Note
Authentication uses Auth0 (OIDC) and opens in your system browser.
Step 3: Walk the onboarding wizard (3 min)
On first launch, AskUI Desktop opens a short setup wizard.
Welcome. A quick tour of what AskUI does, click Get started.
Grant system permissions (macOS only). Allow Screen Recording and Accessibility so the agent can see the screen and control input. The status flips green automatically once granted.
Create your first project, Start from template. Choose Start from
template (recommended) and pick an empty folder. AskUI scaffolds the default
template: tests/ (with ui.md and rules.md), procedures/, and utils/, pre-filled with an
example test and the context files (ui.md, rules.md), ready to run.
You're set. The final screen maps out where everything lives. Click Start testing to open your new project.
Optional: Install AgentOS to automate a computer
Runs are powered by AgentOS, the runtime that actually controls a computer, its screen, keyboard, and mouse. Desktop does not bundle it. To run tests on a computer, such as your local machine, AgentOS must be installed on whichever computer you want to automate. This can be your own machine, a remote host, a headless CI runner, or a device in a fleet.
Manual install required (current version)
We're currently migrating to a newer App version with a more seamless setup experience. The currently released version still requires the manual installation of AgentOS.
You can install AgentOS in one of two ways:
Standalone
Run AgentOS as a regular process in your user session, the fastest option for a dev machine.
OS Service (Windows)
Install as a system service for CI/CD and headless VMs that boot to the login screen.
To use a standalone AgentOS installation with the AskUI Desktop App, point the app at the installed binary:
Open Settings in AskUI Desktop and go to This machine.
Under AgentOS, paste the path to the installed controller. For a pip
install it looks like:
~/py-env/lib/python3.12/site-packages/askui_agent_os/bin/AskuiRemoteDeviceControllerStep 4: Run your first test locally (3 min)
The default template ships with a runnable example test, run it against your own machine to see a full pass end to end.
Open the example test in tests/. It's plain Markdown, readable steps, no
code or selectors. Leave it as-is for this first run.
Run it locally. Start the run against your local machine (this computer). AskUI Desktop launches the agent, which acts on the screen step by step and streams progress into Live Run.
Read the report. Each step shows its status (PASSED, FAILED, WARN,
SKIPPED, or BROKEN) and a screenshot. A green run means every step actually
passed, the agent doesn't improvise its way to done.
Make it yours
Once the example passes, open tests/ui.md on the Tests page and describe your own
app, its main screens, how to tell you're signed in, and any quirks. It's the
single most important file for reliable runs. See
Prompting best practices.
What's next
You have a working project. Here is where to go from here:
Prompting best practices
Learn how to structure prompts so your runs stay reliable as your test suite
grows, the four-file layout, rules.md, and how to avoid brittle tests.
Project structure
Understand what each folder in a Project does and how the runner picks up setup, teardown, and shared procedures automatically.
Run from the CLI
Once your project runs locally, move it to CI in minutes with askui run.
Works with GitHub Actions, GitLab CI, and any headless environment.