Docker Compose Setup

Overview

Docker Compose provides declarative configuration and easier management of Antigravity Manager containers. This method is ideal for persistent deployments on servers and NAS devices.

Prerequisites

Docker Engine 20.10+
Docker Compose V2 (or docker-compose 1.29+)
1GB RAM recommended
Port 8045 available

Quick Start

Step 1: Get the Configuration

Clone Repository
Download Compose File

git clone https://github.com/lbjlaq/Antigravity-Manager.git
cd Antigravity-Manager/docker

mkdir -p antigravity-manager
cd antigravity-manager
curl -O https://raw.githubusercontent.com/lbjlaq/Antigravity-Manager/main/docker/docker-compose.yml

Step 2: Configure Environment

Create a .env file in the same directory:

.env

# API Authentication
API_KEY=sk-your-secure-api-key-here

# Web UI Password (optional, defaults to API_KEY if not set)
WEB_PASSWORD=your-admin-password

# Logging
LOG_LEVEL=info

# Network Binding (true = localhost only, false = all interfaces)
ABV_BIND_LOCAL_ONLY=false

Security: Generate strong, unique values for API_KEY and WEB_PASSWORD. Never commit .env to version control.

Step 3: Start Services

docker compose up -d

Step 4: Verify Installation

# Check container status
docker compose ps

# View logs
docker compose logs -f

# Test health endpoint
curl http://localhost:8045/health

Docker Compose Configuration

Basic Configuration

docker-compose.yml

services:
  antigravity-manager:
    build:
      context: ..
      dockerfile: docker/Dockerfile
    image: lbjlaq/antigravity-manager
    container_name: antigravity-manager
    network_mode: host  # Direct localhost access
    volumes:
      - ~/.antigravity_tools:/root/.antigravity_tools
    environment:
      - LOG_LEVEL=${LOG_LEVEL:-info}
      - API_KEY=${API_KEY:-test}
      - ABV_BIND_LOCAL_ONLY=${ABV_BIND_LOCAL_ONLY:-true}
    restart: unless-stopped

Advanced Configuration

docker-compose.advanced.yml

services:
  antigravity-manager:
    image: lbjlaq/antigravity-manager:latest
    container_name: antigravity-manager
    
    # Use bridge network with port mapping (works on all platforms)
    ports:
      - "8045:8045"
    
    volumes:
      - antigravity-data:/root/.antigravity_tools
      # Optional: custom configuration
      - ./custom-config.json:/root/.antigravity_tools/gui_config.json:ro
    
    environment:
      # Authentication
      - API_KEY=${API_KEY}
      - WEB_PASSWORD=${WEB_PASSWORD}
      - AUTH_MODE=AllExceptHealth
      
      # Performance
      - ABV_MAX_BODY_SIZE=104857600  # 100MB
      
      # Network
      - ABV_BIND_LOCAL_ONLY=false
      - ABV_PUBLIC_URL=https://antigravity.example.com
      
      # Logging
      - LOG_LEVEL=debug
      - RUST_LOG=info
    
    # Resource limits
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 1G
        reservations:
          memory: 256M
    
    # Health check
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8045/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    
    restart: unless-stopped
    
    # Logging
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  antigravity-data:
    driver: local

Environment Variables

string

required

API key for authenticating AI requests.Default in compose: test (change this!)

string

Separate password for Web UI login. Falls back to API_KEY if not set.

string

default:"info"

Options: debug, info, warn, error

boolean

default:"true"

In host network mode, binds to 127.0.0.1 if true, 0.0.0.0 if false.

integer

default:"104857600"

Maximum request size in bytes (default: 100MB)

string

Public URL for OAuth callbacks (e.g., behind reverse proxy)

string

default:"AllExceptHealth"

Authentication mode: Off, Strict, AllExceptHealth, Auto

Network Modes

Host Network (Linux Only)
Bridge Network (All Platforms)
Custom Network

Best for: Direct localhost access, minimal overhead

services:
  antigravity-manager:
    network_mode: host
    environment:
      - ABV_BIND_LOCAL_ONLY=true

Host network mode doesn’t work on macOS/Windows Docker Desktop.

Access at: http://localhost:8045

Best for: Cross-platform compatibility, custom ports

services:
  antigravity-manager:
    ports:
      - "8045:8045"  # or "3000:8045" for custom port
    environment:
      - ABV_BIND_LOCAL_ONLY=false

Access at: http://localhost:8045

Best for: Multi-container setups, service isolation

services:
  antigravity-manager:
    networks:
      - antigravity-net
    ports:
      - "8045:8045"

networks:
  antigravity-net:
    driver: bridge

Volume Management

Named Volume (Recommended)

services:
  antigravity-manager:
    volumes:
      - antigravity-data:/root/.antigravity_tools

volumes:
  antigravity-data:
    driver: local

Benefits:

Docker-managed lifecycle
Easy backup/restore
Platform-independent

Bind Mount

services:
  antigravity-manager:
    volumes:
      - ~/.antigravity_tools:/root/.antigravity_tools
      # Windows: C:\Users\YourName\.antigravity_tools:/root/.antigravity_tools

Benefits:

Direct file access
Easy manual editing
Shared across containers

Managing Services

# Start in background
docker compose up -d

# Start with rebuild
docker compose up -d --build

# Stop containers (preserves data)
docker compose stop

# Stop and remove containers
docker compose down

# Stop and remove containers + volumes
docker compose down -v

# Follow logs
docker compose logs -f

# Last 100 lines
docker compose logs --tail=100

# Service-specific logs
docker compose logs -f antigravity-manager

# Restart all services
docker compose restart

# Restart specific service
docker compose restart antigravity-manager

# Pull latest image
docker compose pull

# Recreate containers
docker compose up -d --force-recreate

Health Checks

Add health checks to monitor service availability:

services:
  antigravity-manager:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8045/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

Check health status:

docker compose ps

Multi-Service Example

Deploy with Nginx reverse proxy:

docker-compose.full.yml

services:
  antigravity-manager:
    image: lbjlaq/antigravity-manager:latest
    container_name: antigravity
    networks:
      - app-network
    volumes:
      - antigravity-data:/root/.antigravity_tools
    environment:
      - API_KEY=${API_KEY}
      - WEB_PASSWORD=${WEB_PASSWORD}
      - ABV_BIND_LOCAL_ONLY=false
      - ABV_PUBLIC_URL=https://antigravity.example.com
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    container_name: nginx-proxy
    networks:
      - app-network
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./ssl:/etc/nginx/ssl:ro
    depends_on:
      - antigravity-manager
    restart: unless-stopped

networks:
  app-network:
    driver: bridge

volumes:
  antigravity-data:
    driver: local

Backup and Restore

Backup Data

# Named volume backup
docker run --rm \
  -v antigravity-data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/antigravity-backup-$(date +%Y%m%d).tar.gz -C /data .

# Bind mount backup
tar czf antigravity-backup-$(date +%Y%m%d).tar.gz ~/.antigravity_tools

Restore Data

# Named volume restore
docker run --rm \
  -v antigravity-data:/data \
  -v $(pwd):/backup \
  alpine tar xzf /backup/antigravity-backup-20260303.tar.gz -C /data

# Bind mount restore
tar xzf antigravity-backup-20260303.tar.gz -C ~/

Local Development Build

For local development with pre-built frontend:

docker-compose.localdist.yml

services:
  antigravity-manager:
    build:
      context: ..
      dockerfile: docker/Dockerfile.localdist
      args:
        USE_MIRROR: auto
    image: antigravity-manager:dev
    # ... rest of config

Build and run:

# Build frontend locally first
npm ci --legacy-peer-deps
npm run build

# Build and start container
docker compose -f docker-compose.yml -f docker-compose.localdist.yml up -d --build

Troubleshooting

Port already in use

Change the host port mapping:

ports:
  - "3000:8045"  # Use port 3000 instead

Permission denied on volume mount

Fix permissions:

sudo chown -R $USER:$USER ~/.antigravity_tools
chmod -R 755 ~/.antigravity_tools

Cannot access from other devices on network

Ensure:

Using bridge network mode (not host)
ABV_BIND_LOCAL_ONLY=false
Firewall allows port 8045
Access via host IP: http://192.168.x.x:8045

Container keeps restarting

Check logs:

docker compose logs --tail=50 antigravity-manager

Disable restart to debug:

restart: "no"

Next Steps

Headless Mode Features

Learn about headless-specific configuration options

Reverse Proxy Setup

Add HTTPS and custom domain with Nginx/Caddy

API Integration

Connect Claude CLI, OpenCode, and other clients

Monitoring

Set up logging and monitoring for production

Getting Started

Core Features

Integration Guides

Configuration

Deployment

Troubleshooting

Overview

Prerequisites

Quick Start

Step 1: Get the Configuration

Step 2: Configure Environment

Step 3: Start Services

Step 4: Verify Installation

Docker Compose Configuration

Basic Configuration

Advanced Configuration

Environment Variables

Network Modes

Volume Management

Named Volume (Recommended)

Bind Mount

Managing Services

Health Checks

Multi-Service Example

Backup and Restore

Backup Data

Restore Data

Local Development Build

Troubleshooting

Next Steps

Headless Mode Features

Reverse Proxy Setup

API Integration

Monitoring

​Overview

​Prerequisites

​Quick Start

​Step 1: Get the Configuration

​Step 2: Configure Environment

​Step 3: Start Services

​Step 4: Verify Installation

​Docker Compose Configuration

​Basic Configuration

​Advanced Configuration

​Environment Variables

​Network Modes

​Volume Management

​Named Volume (Recommended)

​Bind Mount

​Managing Services

​Health Checks

​Multi-Service Example

​Backup and Restore

​Backup Data

​Restore Data

​Local Development Build

​Troubleshooting

​Next Steps

Headless Mode Features

Reverse Proxy Setup

API Integration

Monitoring

Overview

Prerequisites

Quick Start

Step 1: Get the Configuration

Step 2: Configure Environment

Step 3: Start Services

Step 4: Verify Installation

Docker Compose Configuration

Basic Configuration

Advanced Configuration

Environment Variables

Network Modes

Volume Management

Named Volume (Recommended)

Bind Mount

Managing Services

Health Checks

Multi-Service Example

Backup and Restore

Backup Data

Restore Data

Local Development Build

Troubleshooting

Next Steps