Repository Installation Guide

This guide provides step-by-step instructions for setting up the Aurite Agents framework by cloning the main repository. This method is suitable for developers who want to contribute to the framework, delve into its source code, or require the full development environment including the frontend UI and backend services.

For installing Aurite as a Python package to use in your own projects, please see the Package Installation Guide.

Prerequisites

Python >= 3.12
Poetry (Python package and dependency manager)
Node.js (LTS version recommended, for frontend development)
Docker & Docker Compose (for the quickstart script and containerized setup)
redis-server (Required if you plan to use the asynchronous task worker)

Installation

Clone the Repository:

git clone https://github.com/Aurite-ai/aurite-agents.git
cd aurite-agents

Quickstart with Docker (Recommended)

The fastest way to get the entire Aurite Agents environment (Backend API, Frontend UI, and PostgreSQL database) up and running is by using the provided setup script with Docker.

Ensure Docker is running.
Run the appropriate setup script for your operating system:
- For Linux/macOS: In the project root directory (aurite-agents), execute:
```
./scripts/setup.sh
```
- For Windows: In the project root directory (aurite-agents), execute: bat ./scripts/setup.bat These scripts will:
- Check for Docker and Docker Compose.
- Guide you through creating and configuring your .env file (including API keys and project selection).
- Ask if you want to install optional ML dependencies for your local Python environment (useful if you plan to run or develop certain MCP Servers locally that require them).
- Build and start all services using Docker Compose.
Once complete, the backend API will typically be available at http://localhost:8000 and the frontend UI at http://localhost:5173. The script will display the generated API key needed for the UI.

Note on Initial Startup: The backend container might take a few moments to start up completely, especially the first time, as it initializes MCP servers. During this time, the frontend UI might show a temporary connection error. Please allow a minute or two for all services to become fully operational.

Running Docker Compose Directly (Alternative to Setup Scripts)

If you prefer to manage your .env file manually or if the setup scripts encounter issues, you can still use Docker Compose:

Create/Configure .env File: Ensure you have a valid .env file in the project root. You can copy .env.example to .env and fill in the necessary values (especially ANTHROPIC_API_KEY and API_KEY).
Run Docker Compose:
```
docker compose up --build
```
(Use docker-compose if you have an older standalone version).

Manual Installation & Backend Setup

If you prefer to set up and run components manually or without Docker for all services:

Install Python Dependencies: This project uses Poetry for dependency management. First, ensure you have Poetry installed.

From the project root, run the following command to install all required dependencies, including those for development:
```
poetry install --with dev
```
This command reads the pyproject.toml file, resolves the dependencies, and installs them into a dedicated virtual environment managed by Poetry.
Activate the Virtual Environment: To activate the virtual environment and use the installed packages, run:
```
poetry shell
```
All subsequent commands in this guide should be run inside this Poetry shell.
Environment Variables Setup: Before running the system, you need to set up your environment variables.

a. Copy the Example File: In the project root, copy the .env.example file to a new file named .env: bash cp .env.example .env

b. Edit .env: Open the newly created .env file and fill in your specific configurations and secrets. Pay close attention to comments like #REPLACE indicating values you must change.

Key environment variables to configure in your .env file:
- LLM API Key (Required): You must provide an API key for the language model provider you intend to use. For example:
- ANTHROPIC_API_KEY=your_anthropic_api_key
- OPENAI_API_KEY=your_openai_api_key
- (Add other provider keys as needed, e.g., GEMINI_API_KEY) Only one key is strictly necessary to get started, depending on which LLM you configure your agents to use.
- API_KEY (Optional, for API server): A secret key to secure the FastAPI endpoints if you run the API server. Generate a strong random key if you use this. This is pre-configured if you use the setup.sh or setup.bat scripts.
- Configuration Context: The framework automatically detects your project and workspace context by looking for .aurite files. You do not need to set a path manually. Use the aurite init command to create and manage these contexts.
Other variables in the .env file (e.g., for Redis, database persistence like AURITE_ENABLE_DB, AURITE_DB_URL) are optional and only needed if you intend to use those specific features. Review all entries, especially those marked with #REPLACE, and configure them according to your needs.

Important Security Note: Encryption Key
- AURITE_MCP_ENCRYPTION_KEY: This environment variable is used by the framework's SecurityManager to encrypt sensitive data.
- If not set, a key will be auto-generated on startup. This is convenient for quick local testing.
- However, for any persistent deployment, or if you intend to use features that rely on encrypted storage (even for development), it is critical to set this to a strong, persistent, URL-safe base64-encoded 32-byte key.
- Relying on an auto-generated key means that any encrypted data may become inaccessible if the application restarts and generates a new key.
- Please refer to SECURITY.md (to be created) for detailed information on generating, managing, and understanding the importance of this key. You can find AURITE_MCP_ENCRYPTION_KEY commented out in your .env.example file as a reminder.
Running the Backend API Server: The primary way to interact with the framework is through its FastAPI server, which can be started with a simple command:
```
aurite api
```
This command is available after installing the dependencies (Step 2). By default, the server starts on http://0.0.0.0:8000.
Using the CLI: With the framework installed, you can now use the aurite command-line interface to interact with your project.
- List components:
```
aurite list agents
```
- Run an agent interactively:
```
aurite run your_agent_name
```
- Edit configurations in a TUI:
```
aurite edit
```
For a complete guide to all commands, see the CLI Reference.

6. Frontend UI Setup

To set up and run the frontend developer UI for interacting with the Aurite Agents Framework:

Prerequisites: - Node.js >= 18.0.0 - npm >= 8.0.0 - Running Aurite Framework API server (Step 4 above)

Note: Ensure the backend API server is running before starting the frontend if you are not using the Docker quickstart.

Navigate to the Frontend Directory: Open a new terminal or use your existing one to change into the frontend directory:
```
cd frontend
```
Install Frontend Dependencies: Inside the frontend directory, install the necessary Node.js packages for all packages:
```
npm install
```
Build All Packages: Build all packages (required before starting development):
```
npm run build
```

Environment Configuration: Set up environment variables for Aurite Studio:

# Copy environment template for Aurite Studio
cp packages/aurite-studio/.env.example packages/aurite-studio/.env
# Edit packages/aurite-studio/.env with your React app configuration

Create a .env file in the packages/aurite-studio/ directory with:

# API Server URL - where the Aurite API server is running
REACT_APP_API_BASE_URL=http://localhost:8000

# API Key for authentication with the Aurite API server
REACT_APP_API_KEY=your-key-here

Start the Frontend Development Server: Once dependencies are installed and environment is configured, you have two options:

Option A: Start from frontend root (recommended):
```
npm run start
```
Option B: Start from package directory:
```
cd packages/aurite-studio
npm start
```
The frontend UI will be available in your web browser at http://localhost:3000.

Troubleshooting: - If you encounter connection issues, ensure the API server is fully started (it may take a moment to initialize MCP servers) - Verify that your API key matches the one configured in your backend .env file