Installation & Setup
Getting started with BeeAI on your system
BeeAI platform supports installation on macOS, Linux, and Windows through multiple methods.
Installation
BeeAI can be installed using Homebrew, or directly from PyPI. Homebrew is the easiest installation method, as it automatically sets up the needed container runtime using a Lima VM.
Install
Install Homebrew
If you don’t have Homebrew installed, install it with:
Follow the post-installation instructions shown in the terminal to add Homebrew to your PATH.
Install BeeAI
The BeeAI platform will start automatically in a virtualized environment.
Start the BeeAI platform
Update
Uninstall
Install
Install Homebrew
If you don’t have Homebrew installed, install it with:
Follow the post-installation instructions shown in the terminal to add Homebrew to your PATH.
Install BeeAI
The BeeAI platform will start automatically in a virtualized environment.
Start the BeeAI platform
Update
Uninstall
Install
Install a container runtime
BeeAI requires a container runtime to function. Choose one of:
- Rancher Desktop (recommended)
- Docker Desktop
- Podman Desktop
Install and verify the container runtime is working before proceeding.
Install BeeAI
Start the BeeAI Platform
Unlike the Homebrew installation, you’ll need to manually start the BeeAI Platform:
This creates and manages a containerized environment for running agents. The platform needs to be running for agents to work.
Update
Uninstall
Install
Install WSL2
If you don’t already use WSL2 (Windows Subsystem for Linux), install it:
- Open PowerShell or Command Prompt as Administrator
- Run the WSL installation command:
- Restart your computer when prompted
- After restart, a terminal window will open to complete the WSL2 Ubuntu installation
- You will be prompted to create a username and password
Configure WSL2 networking
In order for the agents to be able to auto-register and access Ollama for Windows, it’s necessary to configure the WSL2 networking to a mirrored mode:
-
Download and install the Windows version of Ollama
-
Create or edit the WSL configuration file:
-
Add the following lines:
-
Restart WSL by running in PowerShell:
Install a container runtime
Install one of the following container runtimes. Leave installation options at their default values (use WSL2, use dockerd runtime).
Install Python and pipx
You may install the BeeAI CLI directly in Windows (PowerShell), or in the Ubuntu (WSL2) shell. You can even do both, it’s up to your preference.
Open PowerShell and run:
Windows Store will pop up and offer to install Python. After installing it, re-try the command again to ensure that it now prints the Python version. (If you can’t use Windows Store, you may use a Python installer downloaded from the official website.)
Afterwards, install pipx with:
Then close and re-open the PowerShell window to make sure the pipx command is available.
Open PowerShell and run:
Windows Store will pop up and offer to install Python. After installing it, re-try the command again to ensure that it now prints the Python version. (If you can’t use Windows Store, you may use a Python installer downloaded from the official website.)
Afterwards, install pipx with:
Then close and re-open the PowerShell window to make sure the pipx command is available.
First configure your container runtime to be accessible from WSL2:
- Open Rancher Desktop
- Go to Preferences > WSL Integration
- Enable integration for your Ubuntu WSL2 distro
- Open Rancher Desktop
- Go to Preferences > WSL Integration
- Enable integration for your Ubuntu WSL2 distro
- Open Docker Desktop
- Go to Settings > Resources > WSL Integration
- Enable integration for your Ubuntu WSL2 distro
For Podman Desktop, follow the documentation for socket forwarding to WSL2.
Ensure that docker works in WSL2 by running the following in the Ubuntu (WSL2) shell:
Install pipx with:
Close and re-open the terminal window to make sure the pipx command is available.
Install BeeAI
Start the BeeAI platform
Update
Uninstall
LLM Provider Configuration
After installation, configure your preferred LLM provider.
Run the interactive setup wizard:
The wizard will:
- Help you select from popular LLM providers
- Guide you through API key configuration
- Test the connection to ensure everything works
- Save the configuration for future use
You can re-run this command anytime to change your LLM provider.
Run the interactive setup wizard:
The wizard will:
- Help you select from popular LLM providers
- Guide you through API key configuration
- Test the connection to ensure everything works
- Save the configuration for future use
You can re-run this command anytime to change your LLM provider.
If you prefer to configure your LLM provider manually, use the following examples:
Verify Your Installation
After installation and LLM configuration, verify that everything is working properly:
This command should display a list of available agents.