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

# Installation

> Install and run Voiceblox — choose between Docker (recommended) or a manual setup.

# 🍳 Installation

Now that you have your [ingredients](/getting-started/ingredients) ready, let's install Voiceblox.

***

## Step 1 — Open the Terminal

The terminal is a text window where you type commands. Here's how to open it on your operating system:

<Tabs>
  <Tab title="macOS">
    1. Press **Command (⌘) + Space** to open Spotlight Search.
    2. Type **Terminal** and press **Enter**.
  </Tab>

  <Tab title="Linux">
    * **Ubuntu / Debian:** Press **Ctrl + Alt + T**.
    * Or search for **Terminal** in your applications menu.
  </Tab>

  <Tab title="Windows">
    1. Press the **Windows key**, type **PowerShell**, and click **Windows PowerShell**.
    2. Alternatively, press **Windows key + R**, type `powershell`, and press **Enter**.
  </Tab>
</Tabs>

<Tip>
  Every command in this guide should be typed (or pasted) into the terminal and confirmed with the **Enter** key.
</Tip>

***

## Step 2 — Install Git

Git is the tool used to download the Voiceblox source code.

### Check if Git is already installed

```bash theme={null}
git --version
```

* If you see a version number — **skip to Step 3.**
* If you see `command not found` — install it:

<Tabs>
  <Tab title="macOS">
    ```bash theme={null}
    brew install git
    ```

    > Don't have Homebrew? Install it first:
    >
    > ```bash theme={null}
    > /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
    > ```
  </Tab>

  <Tab title="Linux">
    ```bash theme={null}
    sudo apt-get install -y git
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    winget install Git.Git
    ```

    > Or download the installer from [git-scm.com](https://git-scm.com/download/win). After installation, close and reopen your terminal.
  </Tab>
</Tabs>

***

## Step 3 — Download Voiceblox

In your terminal, run:

```bash theme={null}
git clone https://github.com/voiceblox-ai/voiceblox.git
cd voiceblox
```

This downloads the project into a folder called `voiceblox` and moves you into it.

***

## Step 4 — Choose how to run it

<Tabs>
  <Tab title="🐳 Docker (recommended)">
    Docker is the easiest way to run Voiceblox — no need to install Node.js or any other dependencies.

    ### Check if Docker is already installed

    ```bash theme={null}
    docker --version
    ```

    * If you see a version number — **skip to [Check if Docker is running](#check-if-docker-is-running).**
    * If you see `command not found` — install it below.

    ### Install Docker

    <Tabs>
      <Tab title="macOS">
        ```bash theme={null}
        brew install --cask docker
        ```

        > Don't have Homebrew? Install it first:
        >
        > ```bash theme={null}
        > /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
        > ```

        After installation, open the **Docker** app from your Applications folder to start the Docker engine.
      </Tab>

      <Tab title="Linux">
        ```bash theme={null}
        sudo apt-get update
        sudo apt-get install -y docker.io docker-compose-plugin
        sudo usermod -aG docker $USER
        ```

        > Log out and log back in for the group change to take effect. For other distributions, see [Docker's official install guide](https://docs.docker.com/engine/install/).
      </Tab>

      <Tab title="Windows">
        ```powershell theme={null}
        winget install Docker.DockerDesktop
        ```

        > After installation, open **Docker Desktop** and wait until the Docker engine is running (you should see the Docker icon in your system tray).
      </Tab>
    </Tabs>

    ### Check if Docker is running

    Docker needs to be running before you can start the project. Check with:

    ```bash theme={null}
    docker info
    ```

    * If you see system information — **Docker is running, continue below.**
    * If you see `Cannot connect to the Docker daemon` — open the **Docker Desktop** app (macOS/Windows) or start the service with `sudo systemctl start docker` (Linux), then try again.

    ### Start the project

    Inside the `voiceblox` folder, run:

    ```bash theme={null}
    docker compose up --build
    ```

    This builds the Docker images and starts the project. Two services start at once:

    * **The app** — open your browser at **[http://localhost:3000](http://localhost:3000)** to use the builder
    * **The agent worker** — connects to your LiveKit server and handles voice sessions in the background

    ### Stop the project

    To stop everything, go back to the terminal and press **Ctrl + C**, then run:

    ```bash theme={null}
    docker compose down
    ```
  </Tab>

  <Tab title="💻 Without Docker">
    If you prefer to run Voiceblox without Docker, you'll need Node.js and pnpm.

    ### Install Node.js

    Node.js is the engine that runs Voiceblox. You need **version 20 or newer**.

    #### Check if Node.js is already installed

    ```bash theme={null}
    node --version
    ```

    * If you see something like `v20.x.x` or higher — **you're all set, skip to [Install pnpm](#install-pnpm).**
    * If you see `command not found` or a version below 20 — follow the instructions below.

    <Tabs>
      <Tab title="macOS">
        ```bash theme={null}
        brew install node@20
        ```

        > Don't have Homebrew? Install it first:
        >
        > ```bash theme={null}
        > /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
        > ```

        Confirm it worked:

        ```bash theme={null}
        node --version
        ```
      </Tab>

      <Tab title="Linux">
        Run the following commands one at a time:

        ```bash theme={null}
        curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
        sudo apt-get install -y nodejs
        ```

        Confirm the installation:

        ```bash theme={null}
        node --version
        ```

        > **Other Linux distributions:** See [NodeSource's guide](https://github.com/nodesource/distributions) for RPM-based systems (Fedora, CentOS, etc.).
      </Tab>

      <Tab title="Windows">
        Open **PowerShell** and run:

        ```powershell theme={null}
        winget install OpenJS.NodeJS.LTS
        ```

        > If `winget` is not available, download the installer directly from [nodejs.org](https://nodejs.org/en/download) and run the `.msi` file.

        After installation, **close and reopen PowerShell**, then confirm:

        ```powershell theme={null}
        node --version
        ```
      </Tab>
    </Tabs>

    ### Install pnpm

    `pnpm` is the package manager Voiceblox uses.

    #### Check if pnpm is already installed

    ```bash theme={null}
    pnpm --version
    ```

    * If you see a version number — **you're all set, skip ahead.**
    * If you see `command not found` — install it:

    ```bash theme={null}
    npm install -g pnpm
    ```

    Confirm it worked:

    ```bash theme={null}
    pnpm --version
    ```

    ### Install dependencies

    Inside the `voiceblox` folder, install all required packages:

    ```bash theme={null}
    pnpm install
    ```

    This may take a minute or two. Wait until it finishes before moving on.

    ### Start the app

    Run the development server:

    ```bash theme={null}
    pnpm dev
    ```

    When you see a message like `Ready on http://localhost:3000`, open your web browser and go to:

    **[http://localhost:3000](http://localhost:3000)**

    To stop the server at any time, go back to the terminal and press **Ctrl + C**.
  </Tab>
</Tabs>

***

## Step 5 — Enter Your API Keys

When you open the app for the first time, it will ask you for your API keys — this is where you paste the [ingredients](/getting-started/ingredients) you collected earlier.

1. The setup dialog appears automatically on first launch
2. Paste your **Anthropic API Key** and **Deepgram API Key** (if you have one)
3. Click the **⚙️ Settings** button in the toolbar to add your **LiveKit credentials** (URL, API Key, API Secret)

The app saves everything automatically — **no need to edit any files manually**.

<Note>
  **Docker users:** The agent worker reads keys at startup. If you add keys for a new provider while the containers are running, restart the agent with `docker compose restart agent` for it to pick them up.
</Note>

***

You're all set! Time to build your first agent.

<Card title="🎨 Build Your First Agent" icon="arrow-right" href="/getting-started/first-agent">
  Next step: create a voice agent on the canvas.
</Card>