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

# Local Demo

> Install Qovery locally for demonstration and testing purposes

<Warning>
  **Demo Environment Only**: This local installation is designed for demonstration and testing purposes only. It is **not intended for production use**.
</Warning>

**Time:** \~15 minutes | **Cost:** Free

Install Qovery on your local machine using a k3s Kubernetes cluster. Perfect for learning, testing, and development.

## Prerequisites

Before starting, ensure you have:

**System Requirements:**

* **Operating System**: Linux, macOS, or Windows (WSL only)
* **CPU & Memory**: Minimum 4 CPU cores and 8GB RAM for Docker
* **Software**:
  * Docker (must be running)
  * Git
  * Common utilities: `jq`, `curl`, `sed`, `grep` (usually pre-installed)

**Account:**

* A Qovery account (free) - you'll create one during setup

## Installation Steps

<Steps>
  <Step title="Step 1: Install Qovery CLI">
    <Tabs>
      <Tab title="Linux">
        <Tabs>
          <Tab title="*nix">
            To download and install Qovery CLI on any Linux distribution:

            ```bash theme={null}
            curl -s https://get.qovery.com | bash
            ```

            <Warning>
              The install script does not verify the binary's integrity. For security-sensitive environments, use the **Manual** tab to download a pinned release and verify its checksum against the official [checksums.txt](https://github.com/Qovery/qovery-cli/releases) published with each release.
            </Warning>
          </Tab>

          <Tab title="Arch Linux">
            Qovery is part of [AUR](https://aur.archlinux.org/packages) packages, so you can install it with [yay](https://github.com/Jguer/yay):

            ```bash theme={null}
            yay qovery-cli
            ```
          </Tab>

          <Tab title="Manual">
            Install the Qovery CLI on Linux manually from a [pinned release](https://github.com/Qovery/qovery-cli/releases) to ensure you control what version is installed.

            Replace `X.Y.Z` with the version you want to install:

            ```bash theme={null}
            VERSION=1.48.0  # version number without the 'v' prefix
            ARCH=amd64      # use arm64 for ARM64
            ARCHIVE="qovery-cli_${VERSION}_linux_${ARCH}.tar.gz"

            # Download the binary and checksums for your platform
            curl -sL "https://github.com/Qovery/qovery-cli/releases/download/v${VERSION}/${ARCHIVE}" -o "${ARCHIVE}"
            curl -sL "https://github.com/Qovery/qovery-cli/releases/download/v${VERSION}/checksums.txt" -o checksums.txt

            # Verify the checksum of the downloaded file only (fails if tampered)
            grep "${ARCHIVE}" checksums.txt | sha256sum --check

            # Extract and install
            tar -xzf "${ARCHIVE}"
            mv qovery /usr/local/bin/qovery
            chmod +x /usr/local/bin/qovery
            ```
          </Tab>
        </Tabs>
      </Tab>

      <Tab title="MacOS">
        <Tabs>
          <Tab title="Homebrew">
            The common solution to install a command line binary on the MacOS is to use [Homebrew](https://brew.sh).

            ```bash theme={null}
            # Add Qovery brew repository
            brew tap Qovery/qovery-cli

            # Install the CLI
            brew install qovery-cli
            ```
          </Tab>

          <Tab title="Script">
            To download and install Qovery CLI from the command line:

            ```bash theme={null}
            curl -s https://get.qovery.com | bash
            ```

            <Warning>
              The install script does not verify the binary's integrity. For security-sensitive environments, use the **Manual** tab to download a pinned release and verify its checksum against the official [checksums.txt](https://github.com/Qovery/qovery-cli/releases) published with each release.
            </Warning>
          </Tab>

          <Tab title="Manual">
            Install the Qovery CLI on macOS manually from a [pinned release](https://github.com/Qovery/qovery-cli/releases) to ensure you control what version is installed.

            Replace `X.Y.Z` with the version you want to install:

            ```bash theme={null}
            VERSION=1.48.0  # version number without the 'v' prefix
            ARCH=amd64      # use arm64 for Apple Silicon (M1/M2/M3)
            ARCHIVE="qovery-cli_${VERSION}_darwin_${ARCH}.tar.gz"

            # Download the binary and checksums for your platform
            curl -sL "https://github.com/Qovery/qovery-cli/releases/download/v${VERSION}/${ARCHIVE}" -o "${ARCHIVE}"
            curl -sL "https://github.com/Qovery/qovery-cli/releases/download/v${VERSION}/checksums.txt" -o checksums.txt

            # Verify the checksum of the downloaded file only (fails if tampered)
            grep "${ARCHIVE}" checksums.txt | shasum -a 256 --check

            # Extract and install
            tar -xzf "${ARCHIVE}"
            mv qovery /usr/local/bin/qovery
            chmod +x /usr/local/bin/qovery
            ```
          </Tab>
        </Tabs>
      </Tab>

      <Tab title="Windows">
        <Tabs>
          <Tab title="Scoop">
            The classic way to install binaries on Windows is to use [Scoop](https://scoop.sh).

            ```bash theme={null}
            # Add Qovery bucket
            scoop bucket add qovery https://github.com/Qovery/scoop-qovery-cli

            # Install the CLI
            scoop install qovery-cli
            ```
          </Tab>

          <Tab title="Manual">
            Install the Qovery CLI on Windows manually by downloading the [latest release](https://github.com/Qovery/qovery-cli/releases), and uncompress its content to `C:\Windows`.
          </Tab>
        </Tabs>
      </Tab>

      <Tab title="Docker">
        Install Docker on your local machine and run the following command:

        ```bash theme={null}
        # Pull and Run the latest Qovery CLI
        docker run ghcr.io/qovery/qovery-cli:latest help
        ```

        Change `latest` by the version you want to use. For example, to use the version 0.58.4, run:

        ```bash theme={null}
        docker run ghcr.io/qovery/qovery-cli:0.58.4 help
        ```

        <Info>
          `ghcr.io` is the [GitHub Container Registry](https://github.com/Qovery/qovery-cli/pkgs/container/qovery-cli).
        </Info>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Step 2: Authenticate">
    Sign in to your Qovery account (or create one if you haven't already):

    ```bash theme={null}
    qovery auth
    ```

    This will open your browser to complete the authentication process.

    <Tip>
      **Running in a terminal without browser access?** Use `qovery auth --headless` instead.
    </Tip>
  </Step>

  <Step title="Step 3: Set Context">
    Configure your CLI context:

    ```bash theme={null}
    qovery context set
    ```

    Select your organization when prompted.
  </Step>

  <Step title="Step 4: Deploy Demo Cluster">
    Install a local k3s Kubernetes cluster with Qovery on top:

    ```bash theme={null}
    qovery demo up
    ```

    This command will:

    * Install k3s (lightweight Kubernetes)
    * Install Qovery agent and all required components
    * Configure networking and ingress
    * Take approximately 5-10 minutes to complete

    <Warning>
      **macOS and Windows Users**: You may be prompted for your admin password. This is necessary to properly route traffic from your host to your k3s applications.
    </Warning>
  </Step>

  <Step title="Step 5: Access the Console">
    Once the installation is complete, navigate to [console.qovery.com](https://console.qovery.com)

    You should see your demo cluster connected and ready to use. You can now start deploying applications!
  </Step>
</Steps>

## Using Your Local Cluster

Once your demo cluster is running, you can:

* **Deploy applications** via the [Qovery Console](https://console.qovery.com)
* **Use kubectl** to interact with your local k3s cluster directly
* **Use k9s** for a terminal-based Kubernetes dashboard
* **Follow our tutorials** to deploy your first application

<Tip>
  The demo cluster runs entirely on your local machine, making it perfect for testing and development without cloud costs.
</Tip>

## Cleanup

When you're finished testing, remove the demo cluster:

```bash theme={null}
qovery demo destroy
```

This command removes the local k3s cluster and all Qovery components from your machine.

## What's Next?

<CardGroup cols={2}>
  <Card title="Deploy Your First App" icon="rocket" href="/getting-started/guides/getting-started/deploy-your-first-application">
    Learn how to deploy your first application on Qovery
  </Card>

  <Card title="Qovery CLI" icon="terminal" href="/cli/overview">
    Explore Qovery CLI commands for local development
  </Card>

  <Card title="Move to Production" icon="cloud" href="/getting-started/quickstart">
    Ready to deploy on AWS, GCP, Azure, or Scaleway?
  </Card>

  <Card title="Configuration Guide" icon="sliders" href="/configuration/overview">
    Learn about projects, environments, and services
  </Card>
</CardGroup>