Installation Guide

Deploy AEnvironment development environment from scratch

System Requirements

Basic Dependencies

Environment Check

# Verify Python version
python --version  # Should display 3.12+

# Verify Docker status
docker --version && docker ps

# Verify package manager
pip --version || uv --version

SDK Installation

Installation Methods Comparison

Standard Installation Process

📦 PyPI Installation (Recommended)

# Create virtual environment (optional but recommended)
python -m venv aenv-env
source aenv-env/bin/activate  # Linux/Mac
# or
aenv-env\Scripts\activate     # Windows

# Install SDK
pip install aenvironment

# Verify installation
aenv version

⚡ UV Installation (High Performance)

# Use UV package manager (install uv first)
uv venv aenv-env
source aenv-env/bin/activate
uv pip install aenvironment

🔧 Source Installation (Developers)

# Clone source repository
git clone https://github.com/inclusionAI/AEnvironment.git
cd AEnvironment/aenv

# Development mode installation
pip install -e .

# Verify development environment
python -c "import aenv; print('Development environment ready')"

Installation Verification

✅ Basic Verification

# Check version information
aenv version

Expected Output Example:

AEnv SDK Version: 0.1.0
Environment: PyPI Package
Build Version: 0.1.0
Python version: 3.12.0

🔍 Advanced Verification

# Test CLI functionality
aenv --help

# Check dependency completeness
python -c "import aenv.core; print('Core module loaded successfully')"

Third-party Tool Installation

MCP Inspector Installation (Optional)

# Install MCP debugging tool
npm install -g @modelcontextprotocol/inspector

# Verify installation
mcp-inspector --version

💡 Use Case: MCP Inspector serves as a visual debugging client, recommended for installation in local development environments

Usage

• By default, when you run aenv run, the MCP Inspector will be automatically launched to help you test and monitor your MCP server.

aenv run

SDK Configuration

🛠️ Initialize Configuration

# Create configuration file
aenv config init

# View configuration path
echo "Configuration file location: $(aenv config path)"

Configuration File Structure

Global Configuration

{
  "global": {
    "global_mode": "local",
    "log_level": "INFO"
  },
  "build": {
    "type": "local",
    "build_args": {
      "socket": "unix:///var/run/docker.sock"
    },
    "registry": {
      "host": "docker.io",
      "username": "",
      "password": "",
      "namespace": "aenv"
    }
  },
  "storage": {
    "type": "local",
    "custom": {
      "prefix": "~/.aenv/envs"
    }
  },
  "hub_backend":{
    "hub_backend": "http://xxxx"
  }
}

Configuration Management Operations

Hub Service Configuration

The Hub Service is a centralized metadata storage system for development environments. It works with aenv list and aenv get commands to manage and retrieve environment information.

Local Mode

No configuration required - uses default local storage.

Non-Local Mode

1. Deploy Control Components: First deploy the AEnv management components
2. Get EnvHub Service Address: Obtain the EnvHub service endpoint

# Configure Hub service address (required for non-local mode)
aenv config set hub_config.hub_backend http://localhost:8080

# Verify configuration
aenv config get hub_config

Build Configuration

Docker Socket Configuration Guide

# Standard location check
ls -la /var/run/docker.sock

# Service status verification
sudo systemctl status docker | grep -i sock

# Environment variable confirmation
echo $DOCKER_HOST

# Docker Desktop location
ls -la ~/.docker/run/docker.sock

# Context configuration check
docker context ls
docker context inspect default

# Detailed information view
docker info | grep -i "docker root dir"

# Global Docker socket search
sudo find / -name "docker.sock" 2>/dev/null

# Configuration check
docker version --format '{{json .Server}}' | jq -r '.DockerRootDir'

# Daemon configuration
cat /etc/docker/daemon.json | jq -r '.["hosts"]' 2>/dev/null

Image Registry Configuration

🔒 Security Note: Image registry configuration is used for image pushing during the build process. Configure private registries according to actual needs

# View current configuration
aenv config get build_config.registry

# Configure private registry
aenv config set build_config.registry.host your-registry.com
aenv config set build_config.registry.username your-username
aenv config set build_config.registry.password your-password
aenv config set build_config.registry.namespace your-namespace

Storage Configuration

Storage configuration manages AEnvironment environment code with multi-version support:

# Configure storage path
aenv config set storage_config.custom.prefix ~/.aenv/environments

# View storage configuration
aenv config get storage_config

Management Components Installation

🏠 Local Mode

Features: Zero dependencies, quick start, suitable for development debugging

# No additional components needed
aenv run

# Direct connection to local service
export DUMMY_INSTANCE_IP=http://localhost

☁️ Kubernetes Production Mode

Features: High availability, elastic scaling, enterprise deployment

For detailed Kubernetes deployment instructions, see the {doc}deployment guide, specifically the Kubernetes Mode section.

To package the umbrella chart:

cd deploy
helm dependency update
helm package .

The packaging step produces an archive like aenv-platform-0.1.0.tgz, which can be pushed to your Helm registry.

Chart directory structure (deploy/)

deploy/
├── Chart.yaml
├── values.yaml
├── .helmignore
├── charts/
├── controller/
├── redis/
├── envhub/
└── api-service/

Troubleshooting

Getting Help

# View detailed help
aenv --help

# View failure details --verbose
aenv --verbose build

Next Steps

After installation, we recommend continuing with:

1. 🚀 Quick Start - {doc}quickstart - Create your first environment in 5 minutes
2. 📚 Deep Dive - {doc}concepts - Understand core design principles
3. 🛠️ Hands-on Practice - {doc}../guide/sdk - Master advanced SDK usage

This guide is released under the Apache 2.0 License.