GAIA Docker

Docker containers for AMD GAIA - the AI framework for building and deploying intelligent agents.

Current Versions: gaia-linux: 1.0.0 | gaia-dev: 1.1.0

Overview

This project provides production-ready Docker containers for AMD GAIA in multiple variants, each optimized for different use cases.

Available Containers

Container	Use Case	Installation Method	Documentation
gaia-linux	Production runtime	PyPI at startup	View Docs
gaia-dev	Development + Claude Code	Cloned from source	View Docs
gaia-windows	Windows environments	Planned	View Docs

Quick Start

Choose the container that matches your needs:

For Production Use

Use gaia-linux for running GAIA applications:

docker pull itomek/gaia-linux:1.0.0

# Installs latest GAIA from PyPI automatically
docker run -dit \
  --name gaia-linux \
  -e LEMONADE_BASE_URL=https://your-server.com/api/v1 \
  itomek/gaia-linux:1.0.0

# Or pin a specific GAIA version
docker run -dit \
  --name gaia-linux \
  -e LEMONADE_BASE_URL=https://your-server.com/api/v1 \
  -e GAIA_VERSION=0.15.3.2 \
  itomek/gaia-linux:1.0.0

See gaia-linux documentation for complete usage.

For Development

Use gaia-dev for developing GAIA or contributing to the project:

docker pull itomek/gaia-dev:1.1.0
docker run -dit \
  --name gaia-dev \
  -v gaia-src:/home/gaia/gaia \
  -e LEMONADE_BASE_URL=https://your-server.com/api/v1 \
  -e GAIA_REPO_URL=https://github.com/amd/gaia.git \
  -e GITHUB_TOKEN=ghp_your_token \
  itomek/gaia-dev:1.1.0

See gaia-dev documentation for complete usage.

Key Features

• Decoupled versioning: Image versions track the base environment; GAIA version is chosen at runtime
• Fast installation: Uses uv package manager for 10-100x faster installs than pip
• Complete isolation: Each container is fully self-contained
• Multi-instance support: Run multiple GAIA instances on the same host
• Production-ready: Built on Ubuntu 24.04 LTS with security best practices

Container Comparison

gaia-linux

• Best for: Running GAIA applications, production deployments
• GAIA source: Installed from PyPI at startup (latest or pinned version)
• Includes: Ubuntu 24.04, Python 3.12, Node.js 20, system dependencies
• Size: Smaller (~1-2 GB)
• Startup: 2-3 minutes first run, 30 seconds cached

gaia-dev

• Best for: GAIA development, contributions, experimentation
• GAIA source: Cloned from GitHub, editable install
• Includes: Everything in gaia-linux + Claude Code, network isolation tools
• Size: Larger (~2-3 GB)
• Startup: 3-5 minutes first run, 1 minute cached

gaia-windows (Planned)

• Best for: Windows-specific workflows
• Status: Future feature, in planning phase
• Alternative: Use gaia-linux or gaia-dev with Docker Desktop on Windows

Documentation

Container-Specific Docs

• gaia-linux Documentation - Runtime container guide
• gaia-dev Documentation - Development container guide
• gaia-windows Documentation - Windows container (planned)

Additional Guides

• Using as Base Image - Extend containers in your own Dockerfile
• Building from Source - Build containers locally

Version Management

Docker image versions are managed in VERSION.json. These versions track the base environment (Ubuntu + Python + Node.js + system deps), not the GAIA PyPI package version. GAIA is installed at runtime, so a new GAIA release does not require a new Docker image.

# Pull image (version tracks base environment)
docker pull itomek/gaia-linux:1.0.0
docker pull itomek/gaia-dev:1.1.0

# Use latest GAIA (default)
docker run -dit -e LEMONADE_BASE_URL=... itomek/gaia-linux:1.0.0

# Pin specific GAIA version
docker run -dit -e LEMONADE_BASE_URL=... -e GAIA_VERSION=0.15.3.2 itomek/gaia-linux:1.0.0

When the base environment changes:

1. Update VERSION.json
2. CI automatically builds and publishes new images
3. GitHub release created with version tag

Development

Running Tests

# Install dependencies
uv sync

# Run all tests
uv run pytest tests/ -v

# Run specific test suite
uv run pytest tests/test_dockerfile.py -v

Building Locally

# Build gaia-linux
docker build -f gaia-linux/Dockerfile -t itomek/gaia-linux:1.0.0 .

# Build gaia-dev
docker build -f gaia-dev/Dockerfile -t itomek/gaia-dev:1.1.0 .

See CLAUDE.md for complete development documentation.

Support

• GAIA Framework Issues: https://github.com/amd/gaia/issues
• Docker Container Issues: https://github.com/itomek/gaia-docker/issues
• GAIA Documentation: https://github.com/amd/gaia

Contributing

Contributions welcome! Please:

1. Read CLAUDE.md for project structure and development workflow
2. Open an issue to discuss significant changes
3. Submit pull requests with tests

License

MIT License - see LICENSE file

Related Projects

• AMD GAIA - The AI framework these containers package
• Claude Code - AI coding assistant included in gaia-dev

---

Docker Hub:

• https://hub.docker.com/r/itomek/gaia-linux
• https://hub.docker.com/r/itomek/gaia-dev