Skip to main content

Installation

Install Wren AI locally on macOS, Linux, or Windows. This page covers the fastest launcher-based setup and an optional shell-based setup.

Before you begin​

info

Wren AI only needs your OpenAI API key if you choose OpenAI as the LLM provider. We do not store the key for other purposes.

api_key

Using Wren AI Launcher​

Wren AI Launcher is the easiest way to install Wren AI and start the local services for you.

1. Download and run Wren AI Launcher​

If you are using Apple Silicon Mac, run:

curl -L https://github.com/Canner/WrenAI/releases/latest/download/wren-launcher-darwin-arm64.tar.gz | tar -xz && ./wren-launcher-darwin-arm64

If you are using Intel Mac, run:

curl -L https://github.com/Canner/WrenAI/releases/latest/download/wren-launcher-darwin.tar.gz | tar -xz && ./wren-launcher-darwin
info

You can find other launcher builds on the WrenAI releases page.

2. Allow the app to run​

  1. The launcher may be blocked because it is not yet verified by Apple. mac1
  2. Open System Settings from the Apple menu, then select Privacy & Security.
  3. Find the message that "wren-launcher-darwin" was blocked... and click Allow Anyway. mac2

3. Finish setup in the launcher​

  1. Click Open. mac3
  2. Choose your LLM provider. If you choose a custom provider, follow Custom LLM provider setup. mac4
  3. If you choose OpenAI, enter your OpenAI API key and select the generation model you want to use.
  4. Wait for installation to finish. The launcher will set up the Docker containers and open Wren AI in your browser. mac5

4. Open Wren AI​

If the launcher does not open the site automatically, go to http://localhost:3000.

connect

Using the shell​

You can also launch Wren AI from the shell and pass arguments to skip some setup fields.

note

The examples below prefill OpenAI settings. If you are using another provider, launch Wren AI normally and complete the provider-specific setup separately.

1. Check available arguments​

If you are using Apple Silicon Mac, run:

./wren-launcher-darwin-arm64 -h

If you are using Intel Mac, run:

./wren-launcher-darwin -h

usingShell_mac1

2. Launch Wren AI with OpenAI settings​

If you are using Apple Silicon Mac, run:

./wren-launcher-darwin-arm64 -llm-provider openai -openai-api-key YOUR_OPENAI_API_KEY -openai-generation-model GENERATION_MODEL_NAME

If you are using Intel Mac, run:

./wren-launcher-darwin -llm-provider openai -openai-api-key YOUR_OPENAI_API_KEY -openai-generation-model GENERATION_MODEL_NAME

Wren AI starts automatically after the launcher receives the required OpenAI settings.

usingShell_mac2

Change OpenAI API key​

If you already installed Wren AI with OpenAI and want to use a different API key:

  1. Run Wren AI Launcher again and enter the new OpenAI API key. linux1
  2. Restart the Wren AI service in Docker Desktop by selecting the restart option in the wrenai project. restart

Update Wren AI version​

To upgrade Wren AI:

  1. Download the latest Wren AI Launcher and run it. You can reuse the commands in Using Wren AI Launcher.
  2. Restart the Wren AI service in Docker Desktop by selecting the restart option in the wrenai project. restart

Troubleshooting​

wren-engine fails to start with qemu: uncaught target signal 11​

If you are using Apple Silicon Mac and Wren AI fails to launch with an error like this:

qemu: uncaught target signal 11 (Segmentation fault) - core dumped
Segmentation fault
...

Upgrade Docker Desktop to the latest version, or enable Use Rosetta for x86/amd64 emulation on Apple Silicon in Docker Desktop settings.

troubleshoot