Port Conflicts

AEGIS uses a range of ports for its microservices and infrastructure. Port conflicts are one of the most common issues when starting the platform, especially if you run other development projects alongside AEGIS.

Full Port Map

Application Services

Infrastructure Services

Checking What Is Using a Port

macOS

# Check a specific port
lsof -i :8001
 
# Check all AEGIS ports at once
for port in 3000 5432 6379 8000 8001 8002 8003 8004 8005 8006 8007 8009 9092; do
    pid=$(lsof -ti:$port 2>/dev/null)
    if [ -n "$pid" ]; then
        echo "Port $port: PID $pid ($(ps -p $pid -o comm= 2>/dev/null))"
    else
        echo "Port $port: free"
    fi
done

Linux

# Check a specific port
ss -tlnp | grep :8001
 
# Or using netstat
netstat -tlnp | grep :8001

Killing Conflicting Processes

Kill a Specific Port

# Kill whatever is on port 8001
lsof -ti:8001 | xargs kill -9

Kill All AEGIS Ports

The start-all.sh stop command does this automatically:

./infrastructure/scripts/start-all.sh stop

This kills processes on ports 8000-8007 and 8009 using lsof, and also reads from the .service-pids file to clean up tracked processes.

Kill Infrastructure Containers

# Stop all Docker containers
docker compose down
 
# Or stop a specific container
docker compose stop postgres

Changing Default Ports

Python Services

Each Python service accepts a --port flag via uvicorn. To change the port, modify the startup command:

# Start orchestration engine on port 9001 instead of 8001
cd services/orchestration-engine
poetry run uvicorn orchestration.main:app --port 9001 --host 0.0.0.0

If the service has a config module, you can also set it via environment variable. For example, the memory service reads from settings.PORT:

export PORT=9002
cd services/memory-service
poetry run uvicorn memory.main:app --port $PORT

Infrastructure Ports

To change infrastructure ports, modify docker-compose.yml. The port mapping is in host:container format:

# Change PostgreSQL from 5432 to 15432
services:
  postgres:
    ports:
      - "15432:5432"  # host:container

After changing infrastructure ports, update the corresponding environment variables:

# For a non-standard PostgreSQL port
DATABASE_URL=postgresql://aegis:aegis_local@localhost:15432/aegis

API Gateway Port

The Go gateway runs on port 8000. To change it, modify the gateway’s configuration or pass it as a flag:

cd services/api-gateway
PORT=9000 go run ./cmd/gateway/

Frontend Port

Next.js defaults to port 3000. To change it:

cd frontend
PORT=4000 npm run dev

Or in frontend/package.json:

{
  "scripts": {
    "dev": "next dev -p 4000"
  }
}

Common Port Conflicts by Application

PostgreSQL Conflict (Port 5432)

If you have a system PostgreSQL installation:

# Check if system PostgreSQL is running
pg_isready -h localhost -p 5432
 
# On macOS with Homebrew
brew services stop postgresql@15
 
# Or change the Docker port mapping
# In docker-compose.yml: "15432:5432"

Redis Conflict (Port 6379)

# Check if system Redis is running
redis-cli ping
 
# On macOS with Homebrew
brew services stop redis
 
# Or change the Docker port mapping
# In docker-compose.yml: "16379:6379"

The start-all.sh Port Cleanup

The start-all.sh script handles port cleanup automatically on startup. It runs stop_services() first, which:

1. Reads PIDs from .service-pids and kills each process
2. As a fallback, kills any process on ports 8000-8007 and 8009 using lsof

# From start-all.sh
for port in 8000 8001 8002 8003 8004 8005 8006 8007 8009; do
    lsof -ti:$port | xargs kill -9 2>/dev/null || true
done

This means running start-all.sh after a crash or partial shutdown will clean up stale processes automatically.