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

# Installation

> Install and set up Laddr on your system - complete setup guide with Docker, Python, and environment configuration

Get Laddr installed and configured on your system.

***

## Prerequisites

* **Python 3.9+** - Required for Laddr
* **pip** - Python package manager
* **Docker** (optional but recommended) - For full stack with dashboard
* **Node.js** (optional) - For MCP servers

***

## Python Virtual Environment

Create a virtual environment to isolate dependencies:

```bash theme={null}
python3 -m venv venv
```

Activate the virtual environment:

```bash theme={null}
# On macOS/Linux
source venv/bin/activate

# On Windows (Git Bash or CMD)
.\\venv\\Scripts\\activate
```

<Tip>
  Always activate your virtual environment before installing or using Laddr.
</Tip>

***

## Install Laddr

### Standard Installation

```bash theme={null}
pip install laddr
```

This installs:

* Laddr CLI
* Core framework
* API server
* Worker runtime

### Development Installation

To develop against the Laddr repository:

```bash theme={null}
pip install -e lib/laddr
```

### Verify Installation

```bash theme={null}
laddr --version
laddr --help
```

***

## Docker Setup

For the full experience including the web UI and isolated environments, install Docker:

1. Download from [Docker Desktop](https://www.docker.com/products/docker-desktop)
2. Install and start Docker
3. Verify installation:

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

***

## Create a New Project

Initialize a new Laddr project:

```bash theme={null}
laddr init my_agent_system
cd my_agent_system
```

This creates:

```
my_agent_system/
├── agents/          # Agent definitions
├── workers/         # Worker scripts
├── tools/           # Custom tools
├── Dockerfile       # Docker configuration
├── docker-compose.yml
├── main.py          # Runner script
└── .env.example     # Environment template
```

***

## Configure Environment

Copy the example environment file:

```bash theme={null}
cp .env.example .env
```

Edit `.env` with your configuration:

```bash theme={null}
# .env
# LLM Configuration
GEMINI_API_KEY=your_gemini_api_key
# or
OPENAI_API_KEY=sk-...
# or
ANTHROPIC_API_KEY=sk-ant-...

# Optional: Tool API keys
SERPER_API_KEY=your_serper_api_key

# Queue Backend (default: memory)
QUEUE_BACKEND=memory  # or redis, kafka

# Database (default: sqlite)
DB_BACKEND=sqlite  # or postgresql
DATABASE_URL=sqlite:///./laddr.db

# Storage (default: local)
STORAGE_BACKEND=local  # or minio, s3
```

<Warning>
  Never commit your `.env` file to version control. It contains sensitive API keys.
</Warning>

***

## Run the Stack

### Option 1: Local Development (No Docker)

For quick testing without Docker:

```bash theme={null}
# Set environment
export QUEUE_BACKEND=memory
export DB_BACKEND=sqlite

# Run agent locally
laddr run-local researcher --input '{"query": "test"}'
```

### Option 2: Full Stack (Docker)

Start all services with Docker:

```bash theme={null}
laddr run dev -d
# or
docker compose up -d
```

This starts:

* **PostgreSQL** - Database (port 5432)
* **Redis** - Message queue (port 6379)
* **MinIO** - Object storage (port 9000)
* **API Server** - REST API (port 8000)
* **Dashboard** - Web UI (port 5173)
* **Workers** - Agent workers

Access the dashboard at `http://localhost:5173`

***

## Verify Installation

### Check Services

```bash theme={null}
laddr ps
```

### Run Diagnostics

```bash theme={null}
laddr check
```

This validates:

* Database connectivity
* Queue backend connection
* Storage backend access
* LLM API connectivity
* Agent configuration

### Test with a Simple Agent

```bash theme={null}
# Add a test agent
laddr add agent tester \\
  --role "Test Agent" \\
  --goal "Test the system" \\
  --llm-model gemini-2.5-flash

# Run it
laddr run-local tester --input '{"message": "Hello"}'
```

***

## Troubleshooting

### Command Not Found

If `laddr` command is not found:

```bash theme={null}
# Check if installed
pip show laddr

# Reinstall if needed
pip install --upgrade laddr

# Or use Python module
python -m laddr --version
```

### Docker Issues

If Docker commands fail:

```bash theme={null}
# Check Docker is running
docker ps

# Check Docker Compose
docker compose version

# Restart Docker Desktop if needed
```

### Port Conflicts

If ports are already in use:

```bash theme={null}
# Check what's using the port
lsof -i :8000  # macOS/Linux
netstat -ano | findstr :8000  # Windows

# Change ports in docker-compose.yml
```

### API Key Errors

Ensure your API keys are valid:

```bash theme={null}
# Test API key
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=YOUR_KEY
```

***

## Next Steps

* [First Agent](/getting-started/first-agent) - Build your first agent
* [Playground](/getting-started/playground) - Explore the dashboard
* [Agent Configuration](/guides/agents/agent-config) - Configure agents
* [Local Runtime](/guides/local-runtime) - Local development guide