Installation

This guide walks you through installing BindAI and preparing your development environment. There are two main ways to use BindAI:

Install the published packages from PyPI — recommended for application development.
Clone the GitHub repository and use the uv workspace — recommended for contributors and framework development.

Requirements

Before installing BindAI, make sure you have:

Python 3.12 or newer
pip
Git (recommended for source development)
uv for source development

Verify your Python version:

python --version

BindAI v0.1 requires Python 3.12 or newer.

Install BindAI from PyPI

The easiest way to install BindAI is from PyPI:

python -m pip install bindai

You can also use:

pip install bindai

After installation, verify the BindAI CLI:

bindai version

The CLI version changes as BindAI is released. Do not rely on a hardcoded version number in your application or documentation.

Verify the Python Package

Verify that the BindAI Python package is available:

python -c "import bindai; print('BindAI import OK')"

Expected output:

BindAI import OK

Install Optional BindAI Packages

BindAI is organized into multiple packages. The main bindai package provides the core framework experience. Additional capabilities are available through separate packages.

REST API

Install the BindAI REST API package:

python -m pip install bindai-api

This package provides HTTP endpoints for:

Agent execution
Agent streaming
Workflow execution
Project access
Background automation runs
Run status
Health checks

Connections

Install the BindAI Connections package:

python -m pip install bindai-connections

Current integrations include:

Webhooks
GitHub
Slack
Discord
Notion
Jira
Resend
Vercel
Netlify
Google Sheets
Google Docs
Gmail
Google Drive

See the Connections documentation for details.

Create Your First Project

Generate a new BindAI project:

bindai new my-agent

Move into the generated project:

cd my-agent

The generated project provides the structure needed to build a BindAI application.

Configure Project Settings

BindAI projects use bindai.toml for project configuration. The CLI can be used to inspect and update supported configuration values. Show the current project configuration:

bindai config show

Set the provider:

bindai config set provider openai

Set the model:

bindai config set model gpt-4.1-mini

You can also read an individual configuration value:

bindai config get provider

Configuration values are stored in the project’s bindai.toml file.

Configure Environment Variables

AI providers generally require credentials. Configure the required credentials in your environment or project .env file. For example:

OPENAI_API_KEY=your_api_key_here

Depending on the provider you use, other environment variables may be required. Common provider credentials include:

OPENAI_API_KEY=your_api_key_here
ANTHROPIC_API_KEY=your_api_key_here
GEMINI_API_KEY=your_api_key_here
GROQ_API_KEY=your_api_key_here
OPENROUTER_API_KEY=your_api_key_here

Local providers such as Ollama may not require a hosted API key. Keep API keys and other credentials out of source control.

Use Project-Scoped Provider Connections

BindAI also supports named provider connections for storing provider credentials separately from project configuration. A provider connection has:

A connection name
A provider name
Connection metadata stored in .bindai/connections.toml
A provider credential stored in the operating system credential store

Create a provider connection with:

bindai connections add

List configured provider connections with:

bindai connections list

Remove a provider connection with:

bindai connections remove

After creating a connection, select it for the project:

bindai config set connection work

For example, a project can use:

provider = "openai"
connection = "work"

The provider credential itself is stored through the operating system credential store rather than in bindai.toml. Provider credential resolution follows this precedence:

An explicitly supplied API key
The credential stored for the selected project connection
The provider environment variable

The selected connection must exist and must match the configured provider. This approach allows projects to use named provider credentials without placing API keys directly in project configuration or source code.

Verify Your Environment

Run the built-in diagnostics:

bindai doctor

The doctor command checks the BindAI environment and reports detected configuration or installation issues. For projects using a named provider connection, bindai doctor also reports the configured connection and whether its stored credential is available.

Run Your Project

Start the generated application:

bindai run

If the required configuration is available, the generated project can start its BindAI application environment.

Docker Deployment

BindAI v0.1 includes Docker support for running the BindAI API service. From the BindAI repository root, build the Docker image:

docker build -t bindai-api .

Run the container on Windows PowerShell:

docker run --rm -p 8000:8000 `
  -e BINDAI_API_KEY=your-secret-key `
  bindai-api

On macOS or Linux:

docker run --rm -p 8000:8000 \
  -e BINDAI_API_KEY=your-secret-key \
  bindai-api

The API will be available at:

http://localhost:8000

Verify the service with the health endpoint:

http://localhost:8000/health

The health endpoint does not require authentication.

Docker Compose

The repository also includes a Docker Compose configuration. Start the API service with:

docker compose up --build

Stop the service with:

docker compose down

The API will be available at:

http://localhost:8000

Configure required environment variables through your local environment or .env file. Do not commit API keys or other secrets to source control. See Project Deployment for more information.

API Authentication

Protected BindAI API endpoints use an API key. Configure:

BINDAI_API_KEY=your-secret-key

Then authenticate requests using:

Authorization: Bearer your-secret-key

The /health endpoint is public. Resource endpoints require authentication. The v0.1 API uses a simple environment-based API key. Persistent API-key management and more advanced authentication are planned for future releases.

Background Execution

BindAI v0.1 provides background automation execution through the automation worker. Background runs can be submitted through the REST API and queried by run ID. The v0.1 implementation uses in-process execution. Distributed queue-based workers are planned for a future release and are not required for the v0.1 release.

Install BindAI from GitHub for Development

If you want to contribute to BindAI or work with the latest source code, clone the repository:

git clone https://github.com/BindBrain/BindAI.git
cd BindAI

BindAI is organized as a multi-package uv workspace. The repository contains multiple BindAI packages under:

packages/

The workspace includes separate packages for areas such as:

Core functionality
Agents
Tools
Providers
Memory
Embeddings
Retrieval
Knowledge
Workflows
Projects
Automation
Connections
Runtime
REST API
MCP
CLI

Install uv

If uv is not already installed, install it with:

python -m pip install uv

Verify the installation:

uv --version

Synchronize the Development Workspace

From the repository root, run:

uv sync

This synchronizes the workspace dependencies and creates or updates the development virtual environment.

Activate the Development Environment

Windows PowerShell

.\.venv\Scripts\Activate.ps1

macOS / Linux

source .venv/bin/activate

After activation, your terminal should display the active environment.

Verify the Source Installation

Verify that Python is using the workspace environment:

python -c "import sys; print(sys.executable)"

Then verify the BindAI package:

python -c "import bindai; print('BindAI import OK')"

Expected output:

BindAI import OK

Finally, verify the CLI:

bindai version

Important: Do Not Use Root-Level Editable Installation

Because the BindAI repository is a multi-package uv workspace, do not run:

pip install -e .

from the repository root. Use:

uv sync

instead. Individual BindAI packages are located under:

packages/

and are managed together through the workspace configuration. This keeps workspace dependencies consistent across the repository.

Development Workflow

When working on BindAI from source, a typical workflow is:

git pull
uv sync

Activate the environment if necessary.

Windows PowerShell

.\.venv\Scripts\Activate.ps1

macOS / Linux

source .venv/bin/activate

Then run the test suite or work on the relevant package. Run the main test suite with:

uv run pytest tests -q

To test an individual package:

uv run pytest packages/bindai-api/tests -q

BindAI uses a modular package structure, so changes to one package can be developed and tested independently while still being synchronized through the workspace.

Updating BindAI

To upgrade the published PyPI package:

python -m pip install --upgrade bindai

Then verify the installed version:

bindai version

To upgrade optional packages:

python -m pip install --upgrade bindai-api bindai-connections

If you are developing from the source repository, update the repository and synchronize the workspace:

git pull
uv sync

Common Issues

`ModuleNotFoundError`

Make sure the correct environment is activated. For source development, activate the workspace environment.

Windows PowerShell

.\.venv\Scripts\Activate.ps1

macOS / Linux

source .venv/bin/activate

Then verify:

python -c "import bindai; print('BindAI import OK')"

CLI Not Found

If the bindai command is unavailable after installation, make sure the environment containing BindAI is activated. For source development, activate the .venv created by uv sync. You can also verify which Python executable is being used:

python -c "import sys; print(sys.executable)"

Then verify:

bindai version

Missing API Key

If a provider reports an authentication error, verify that the required environment variable is configured. For example:

OPENAI_API_KEY=your_api_key_here

Make sure the variable is available to the environment in which BindAI is running. If you use a .env file, ensure it is located where your application expects it and that your application loads environment variables appropriately. If you are using a project-scoped provider connection instead, verify the connection:

bindai connections list

Then check the project configuration:

bindai config get connection

Finally, run:

bindai doctor

Unsupported Python Version

Check your Python version:

python --version

BindAI v0.1 requires Python 3.12 or newer.

Provider Configuration Issues

If your application cannot connect to a language model:

Verify that the required API key or local provider configuration is available.
Confirm the selected provider.
Confirm that the selected model is supported by that provider.
If using a named connection, verify that the connection exists and matches the selected provider.
Run:

bindai doctor

Check the provider-specific documentation for additional configuration requirements.

Current provider integrations include:

OpenAI
Anthropic
Google Gemini
Groq
Ollama
OpenRouter

Workspace Installation Issues

If source dependencies appear to be missing or inconsistent, run:

uv sync

Make sure the command is executed from the BindAI repository root. Avoid installing the entire repository with:

pip install -e .

The repository is managed as a multi-package workspace.

Docker Issues

If the Docker API container does not start:

Verify Docker is installed and running.
Build the image again:

docker build -t bindai-api .

Verify that port 8000 is available.
Make sure BINDAI_API_KEY is configured when running the Docker container.

For Docker Compose:

docker compose up --build

To stop the service:

docker compose down

Next Steps

After installing BindAI, continue with:

These guides introduce the core BindAI development workflow. As you become familiar with the framework, explore:

Tools
Memory
Knowledge and RAG
Workflows
Projects
Connections
REST API
Automation
MCP
Multi-Agent Systems

For the overall implementation status, see the ROADMAP.

​Installation

​Requirements

​Install BindAI from PyPI

​Verify the Python Package

​Install Optional BindAI Packages

​REST API

​Connections

​Create Your First Project

​Configure Project Settings

​Configure Environment Variables

​Use Project-Scoped Provider Connections

​Verify Your Environment

​Run Your Project

​Docker Deployment

​Docker Compose

​API Authentication

​Background Execution

​Install BindAI from GitHub for Development

​Install uv

​Synchronize the Development Workspace

​Activate the Development Environment

​Windows PowerShell

​macOS / Linux

​Verify the Source Installation

​Important: Do Not Use Root-Level Editable Installation

​Development Workflow

​Windows PowerShell

​macOS / Linux

​Updating BindAI

​Common Issues

​ModuleNotFoundError

​Windows PowerShell

​macOS / Linux

​CLI Not Found

​Missing API Key

​Unsupported Python Version

​Provider Configuration Issues

​Workspace Installation Issues

​Docker Issues

​Next Steps

Installation

Requirements

Install BindAI from PyPI

Verify the Python Package

Install Optional BindAI Packages

REST API

Connections

Create Your First Project

Configure Project Settings

Configure Environment Variables

Use Project-Scoped Provider Connections

Verify Your Environment

Run Your Project

Docker Deployment

Docker Compose

API Authentication

Background Execution

Install BindAI from GitHub for Development

Install uv

Synchronize the Development Workspace

Activate the Development Environment

Windows PowerShell

macOS / Linux

Verify the Source Installation

Important: Do Not Use Root-Level Editable Installation

Development Workflow

Windows PowerShell

macOS / Linux

Updating BindAI

Common Issues

`ModuleNotFoundError`

Windows PowerShell

macOS / Linux

CLI Not Found

Missing API Key

Unsupported Python Version

Provider Configuration Issues

Workspace Installation Issues

Docker Issues

Next Steps