LocalStack

 

<!-- ![LocalStack Banner](profile/mainbanner.png) -->

**The LocalStack for AI Agents** - Enterprise-grade mock API platform for OpenAI, Anthropic, Google Gemini.
Develop, Test, and Scale AI Agents locally without burning API credits.

[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Docker](https://img.shields.io/badge/docker-ready-brightgreen.svg)](https://hub.docker.com/r/ai-localstack/ai-localstack)

> **Save $500-50,000/month** on API costs while making tests **80× faster** and **100% reliable**.
> "If you are building Agents, you need this."

---

## 🚀 Quick Start (Docker Compose)

The easiest way to run AI LocalStack is using Docker Compose. This spins up the API, Database, Vector Store, and Redis cache instantly.

---

### 👉 Windows (One-Click)
Simply run the `start_windows.bat` file in the root directory.
It will:
1. Check Docker status
2. Build the project
3. Open the Dashboard in your browser automatically.

---

### 👉 Mac/Linux (Terminal)

### 1. Start the Stack
Navigate to the `ai-localstack` backend directory and start the services:

```bash
cd ai-localstack
docker-compose up --build
```
This will start the following services:
- **API**: `http://localhost:8000`
- **Qdrant** (Vector DB): `localhost:6333`
- **PostgreSQL**: `localhost:5432`
- **Redis**: `localhost:6379`

### 2. Verify Installation
```bash
# Health check
curl http://localhost:8000/health
# {"status":"ok"}
```

---

### 3. Enable Magic Mode (Optional / Extension)

To use the **"Magic Record"** feature (Proxy to Real OpenAI once -> Save -> Replay forever):

1. **Edit Environment**:
   Open `ai-localstack/.env` and add:
   ```properties
   AI_LOCALSTACK_PROXY_MODE=True
   AI_LOCALSTACK_OPENAI_REAL_KEY=sk-your-real-openai-key
   ```
2. **Restart**:
   ```bash
   docker-compose restart
   ```
3. **Usage**:
   - Run