# AutoGPT (Platform) Knowledge Base

AutoGPT (specifically the platform version) has a complex Docker setup involving multiple networks, nested `extends`, and dependencies on Supabase.

## Armorer Hints (Machine Readable)
```json
{
  "create_files": [
    {
      "path": "docker-compose.yml",
      "content": "version: \"3.9\"\nservices:\n  auto-gpt:\n    image: significantgravitas/auto-gpt:latest\n    env_file:\n      - .env\n    command: [\"serve\"]\n    ports:\n      - \"8000:8000\"\n    volumes:\n      - ./data:/app/data\n      - ./logs:/app/logs\n"
    }
  ]
}
```

## Prerequisites
- Node.js & NPM
- Docker & Docker Compose
- PNPM (for frontend development)
- Poetry (for backend development)

## Deployment

### Quick Setup (Recommended for Local-Host)
```bash
# macOS/Linux
curl -fsSL https://setup.agpt.co/install.sh -o install.sh && bash install.sh
```

### Manual Setup (Robust Method)
1. **Clone & Navigate:**
   ```bash
   git clone https://github.com/Significant-Gravitas/AutoGPT.git installed/AutoGPT
   cd installed/AutoGPT/autogpt_platform
   ```

2. **Initialize Environment:**
   Run the platform's initialization if available, or manually copy defaults:
   ```bash
   cp .env.default .env
   cp backend/.env.default backend/.env
   cp frontend/.env.default frontend/.env
   touch db/docker/.env
   ```

3. **Apply Compatibility Fixes (If Docker < v2.24):**
   If `docker compose config` fails with `env_file` map errors or `develop` block errors, you must patch the files.
   **Do NOT move to /tmp.**
   
   **Python Fix Script (Recommended):**
   Create a script `fix_compose.py` to regex-replace:
   - `env_file` maps -> simple lists
   - remove `develop:` blocks entirely
   
   **Or Manual Edits:**
   - `autogpt_platform/docker-compose.platform.yml`
   - `autogpt_platform/db/docker/docker-compose.yml`

4. **Start Stack:**
   For heavy stacks like this, startup order can be tricky. Run twice to ensure dependencies catch up:
   ```bash
   # First run (builds and starts DB)
   docker compose up -d --build
   
   # Second run (ensures dependents start after DB is healthy)
   docker compose up -d
   ```

## Security Hardening

### Network Exposure
By default, AutoGPT exposes ports (3000, 8000, 8006, etc.) on `0.0.0.0`, making them accessible to the entire network.

**To Harden (Local Access Only):**
Modify the `ports` section in `docker-compose.platform.yml` to bind specifically to localhost:
```yaml
ports:
  - "127.0.0.1:3000:3000" # Frontend
  - "127.0.0.1:8000:8000" # Supabase/Kong
  - "127.0.0.1:8006:8006" # API
```

### Secrets Management
- **Avoid `.env` in Production:** For production, use Docker Secrets or a dedicated secrets manager instead of mounting `.env` files.
- **File Permissions:** Ensure `.env` files are `600` (read/write only by owner).
  ```bash
  chmod 600 .env backend/.env frontend/.env
  ```

### User Privileges
- **Non-Root:** Most AutoGPT services run as `root` inside the container by default (Python images). To run as a non-root user, you would need to modify the `Dockerfile` to create a user and `USER appuser`.
- **Database:** Supabase runs as `postgres` (non-root) correctly.

## External Services

### Using Managed Supabase (Cloud)
To use a managed Supabase project instead of the local Docker stack:

1.  **Stop Local Database:**
    You can disable the `db`, `kong`, `auth`, `rest`, `realtime`, `storage`, `imgproxy`, `meta`, `functions`, `analytics`, `vector`, and `supavisor` services in `docker-compose.yml` to save resources.

2.  **Update `backend/.env`:**
    Modify the following variables to point to your managed instance:
    ```bash
    # Database Connection (Transaction Pooler recommended)
    DB_HOST=aws-0-us-east-1.pooler.supabase.com
    DB_PORT=6543
    DB_USER=postgres.your-project-ref
    DB_PASS=your-db-password
    DB_NAME=postgres

    # Supabase API
    SUPABASE_URL=https://your-project-ref.supabase.co
    SUPABASE_SERVICE_ROLE_KEY=eyJh... (from Project Settings > API)
    JWT_VERIFY_KEY=... (from Project Settings > API > JWT Secret)
    ```

3.  **Update `frontend/.env`:**
    ```bash
    NEXT_PUBLIC_SUPABASE_URL=https://your-project-ref.supabase.co
    NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJh... (from Project Settings > API)
    ```

### Other Remote Services
All other external services (Redis, RabbitMQ, LLMs) are configured in `backend/.env`.
- **Redis:** Set `REDIS_HOST` and `REDIS_PASSWORD`.
- **RabbitMQ:** Set `RABBITMQ_HOST`, `RABBITMQ_DEFAULT_USER`, `RABBITMQ_DEFAULT_PASS`.
- **LLMs:** Set `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.

### Makefile Reference (Within `autogpt_platform`)
Use these commands for common tasks instead of calling Docker directly when possible:

| Command | Action |
| --- | --- |
| `make start-core` | Start Supabase, Redis, RabbitMQ (background) |
| `make stop-core` | Stop the core services |
| `make logs-core` | Tail core service logs |
| `make format` | Format & lint backend (Python) and frontend (TS) |
| `make migrate` | Run backend database migrations |
| `make run-backend` | Run FastAPI server (requires local environment) |
| `make run-frontend` | Run Next.js dev server (requires local environment) |

## Configuration & Health

### Ports
- **Frontend UI**: 3000
- **REST API Server**: 8006
- **Websocket Server**: 8001
- **Supabase (Kong)**: 8000

### Encryption Keys
To generate a new encryption key for `ENCRYPTION_KEY` in `.env`:
```bash
# Via Poetry
cd backend && poetry run cli gen-encrypt-key
# OR via Python
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
```

### Windows/WSL2 Warning
When installing on Windows, **WSL 2** is mandatory. Using Hyper-V often causes `supabase-db` to remain unhealthy. Ensure "Use the WSL 2 based engine" is checked in Docker Desktop settings.

## Troubleshooting

### 1. Docker Compose Compatibility (`env_file` syntax)
**Context:** AutoGPT uses modern `env_file` syntax (v2.24+) with `required: false`. This causes `config` errors on older Docker versions:
`'env_file[1]' expected type 'string', got unconvertible type 'map[string]interface {}'`

**🚨 CRITICAL FIX INSTRUCTIONS:**
1. **DO NOT MOVE FILES:** Never attempt to copy the project to `/tmp` to fix this. You must edit the files **IN PLACE** within `installed/AutoGPT`.
2. **TARGET FILES:** You must check and fix ALL occurrences, including:
   - `autogpt_platform/docker-compose.platform.yml`
   - `autogpt_platform/db/docker/docker-compose.yml`
   - `classic/original_autogpt/docker-compose.yml`
3. **THE FIX:** Locate the `env_file` section and convert it to a simple list.
   ```yaml
   # ❌ BAD (Modern):
   env_file:
     - path: backend/.env
       required: false

   # ❌ BAD (Inline Variables - DO NOT DO THIS):
   # This fails because the variables are not set in the host shell!
   environment:
     - OPENAI_API_KEY=${OPENAI_API_KEY}

   # ✅ GOOD (Legacy Compatible):
   env_file:
     - backend/.env
   ```
4. **MANDATORY FILES:** Since you removed `required: false`, you MUST ensure the referenced file exists. Use `touch` to create it if missing.

### 2. Missing Environment Files
When using string-list syntax for `env_file` on older versions, **all files are mandatory**. Ensure these exist (even if empty):
- `.env`
- `backend/.env`
- `frontend/.env`
- `db/docker/.env`

### 3. Startup Order & Dependencies
- `migrate` service MUST complete successfully before `rest_server` or `executor` can run.
- `db` MUST be healthy before `migrate` starts. Check logs via `docker compose logs -f migrate`.
