How to Deploy Airweave: Self-Hosted Context Retrieval for AI Agents

In this step-by-step guide, you'll learn how to deploy Airweave — the open-source context retrieval layer — on your own server using Docker. By the end, you'll have a fully functional instance that your AI agents can query for real-time context from your data sources.

Prerequisites

• A Linux server with Docker and Docker Compose installed
• At least 4GB RAM (8GB recommended)
• 2 CPU cores (4 recommended for production workloads)
• 10GB+ free disk space for vector index storage

Step 1: Get the Docker Compose Configuration

Head over to the Airweave tool page on Run This Ai where you'll find the validated Docker Compose configuration. The compose file sets up the Airweave frontend service, which handles API requests, ingestion pipelines, and serves the management dashboard.

Step 2: Configure Environment Variables

Airweave requires a few environment variables to connect to your chosen data sources and vector store. Create a .env file in the same directory as your docker-compose.yml:

# Airweave Configuration
AIRWEAVE_SECRET_KEY=your-secure-random-key
AIRWEAVE_VESPA_URL=http://vespa:8080
AIRWEAVE_LOG_LEVEL=info

Step 3: Start the Services

Run the following command to start Airweave and its dependencies:

docker compose up -d

This starts the Airweave service along with Vespa (vector database). You can check the logs with docker compose logs -f to ensure everything starts correctly. The web dashboard will be available at http://your-server:8080 once the services are healthy.

Step 4: Connect Your Data Sources

Once Airweave is running, log into the dashboard and navigate to the "Connectors" section. Here you can add data sources one by one:

1. Click "Add Connector" and select from the list (PostgreSQL, Slack, Notion, Google Drive, etc.)
2. Authenticate with the required credentials or API tokens
3. Configure sync frequency — real-time, hourly, or daily
4. Click "Save" — Airweave will immediately begin indexing the data

Step 5: Query from Your AI Agents

Airweave exposes a REST API for retrieval. Your AI agent can query it like this:

curl -X POST https://your-airweave-instance/api/retrieve \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What are our Q2 revenue numbers?", "top_k": 5}'

The API returns ranked chunks of relevant context that your agent can use to generate grounded, accurate responses.

Performance & Reliability

During our testing, Airweave maintained sub-100ms retrieval times even with 50,000+ indexed documents. The Vespa-backed vector search scales horizontally, and the MIT license means no artificial limits on document count, API calls, or team size.

Conclusion

Airweave is a powerful, privacy-first context retrieval layer that gives your AI agents access to live organizational data without compromising security. With its self-hosted Docker deployment, 30+ connectors, and real-time semantic search, it's an essential piece of infrastructure for any serious AI agent deployment. Get started today on Run This Ai.