> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finalrun.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Install FinalRun on macOS, Linux, or Windows

> Run the one-line installer for your OS and verify your host with finalrun doctor.

FinalRun ships as a standalone binary. The one-line installer downloads it, puts it on your `PATH`, and walks you through Android and iOS host tooling. Once it finishes, you can jump straight to the [Quickstart](/quickstart).

## Install

<Tabs>
  <Tab title="macOS">
    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/final-run/finalrun-agent/main/scripts/install.sh | bash
    ```
  </Tab>

  <Tab title="Linux">
    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/final-run/finalrun-agent/main/scripts/install.sh | bash
    ```

    Linux supports Android local execution. iOS testing is macOS-only — use `finalrun cloud test` for iOS from Linux.
  </Tab>

  <Tab title="Windows">
    Run in PowerShell:

    ```powershell theme={null}
    irm https://raw.githubusercontent.com/final-run/finalrun-agent/main/scripts/install.ps1 | iex
    ```

    Windows supports Android local execution. iOS testing is macOS-only — use `finalrun cloud test` for iOS from Windows.
  </Tab>
</Tabs>

### What the installer does

1. Downloads the prebuilt `finalrun` binary to `~/.finalrun/bin/` and symlinks it to `~/.local/bin/finalrun` (or `%USERPROFILE%\.finalrun\bin\` on Windows).
2. Updates your shell rc files (`.bashrc`, `.zshrc`, `.profile`, fish config) so `finalrun` is on your `PATH` in new shells.
3. Downloads the matching runtime tarball into `~/.finalrun/runtime/<version>/`.
4. Prompts you for Android, iOS, or both, then installs `scrcpy` and/or `applesimutils` via Homebrew when missing.
5. Installs the FinalRun [AI agent skills](/running/ai-agent-skills) via `npx skills add` (requires Node.js 20+ — skipped with a warning if `npx` isn't available).
6. Runs `finalrun doctor` to verify host readiness.
7. Detects existing API keys in your environment and prints next steps.

## Manual prerequisites

The tooling below isn't auto-installable — you have to provision it yourself before running local tests on that platform. Cloud-only users can skip this section entirely.

<Tabs>
  <Tab title="Android (local)">
    | Tool        | How to provide                                                                                                                                                                                              |
    | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Android SDK | Install via [Android Studio](https://developer.android.com/studio) or the standalone command-line tools. Set `ANDROID_HOME` (or `ANDROID_SDK_ROOT`), or put `platform-tools` and `emulator` on your `PATH`. |
    | `adb`       | Ships with the Android SDK platform-tools.                                                                                                                                                                  |
  </Tab>

  <Tab title="iOS (local, macOS only)">
    <Warning>
      iOS simulators require the **full Xcode app** from the App Store — Xcode Command Line Tools alone are not enough. The installer rejects CLT-only setups because `xcrun simctl` ships only with Xcode.
    </Warning>

    | Tool             | How to provide                                                                                                                                       |
    | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
    | macOS            | iOS simulator support is macOS-only.                                                                                                                 |
    | Xcode (full app) | Install from the App Store, launch once to accept the license, then run `sudo xcode-select -s /Applications/Xcode.app/Contents/Developer` if needed. |
  </Tab>
</Tabs>

## Verify

The interactive installer runs `finalrun doctor` for you at the end. To re-check at any time:

```bash theme={null}
finalrun --help
finalrun doctor
```

Check a single platform:

```bash theme={null}
finalrun doctor --platform android
finalrun doctor --platform ios
```

If `finalrun` isn't found, open a new shell — the rc files were updated for new sessions. On Windows, restart your terminal.

## Set an API key

The fastest way to get started is FinalRun Cloud — sign up, drop in one key, and run. If you'd rather use your own AI provider account, that path works too.

<CardGroup cols={2}>
  <Card title="FinalRun Cloud — recommended" icon="cloud" href="/configuration/cloud-api-key">
    Grab a [FinalRun Cloud API key](/configuration/cloud-api-key) at [cloud.finalrun.app](https://cloud.finalrun.app) and set `FINALRUN_API_KEY`. Managed AI, no provider account needed, and new accounts get \$5 of free credits.
  </Card>

  <Card title="Bring your own provider key" icon="key" href="/configuration/ai-providers">
    Use your own [Google, OpenAI, or Anthropic API key](/configuration/ai-providers) (`GOOGLE_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`). Standard provider billing applies.
  </Card>
</CardGroup>

## Upgrade

```bash theme={null}
finalrun upgrade
```

Pulls the latest release and replaces the binary and runtime in place.

## Next steps

<Card title="Quickstart" icon="rocket" href="/quickstart">
  Generate, run, and fix your first FinalRun test from your AI coding agent.
</Card>