port-management

Port Management Rules

Objective

Prevent port conflicts across all projects on this machine using AEC's port registry.

When this rule applies

The port registry is opt-in. Follow this rule only in a project whose AGENTINFO.md contains the <!-- aec-port-registry:start --> marker; AEC writes that marked block when the user enables the registry and removes it when they turn it off. Without the marker (a ## Port Registry heading alone does not count), the user has opted out: do not run aec ports or require registration, and choose ports as the project already does.

Port Management System

Where ports live

• Per project: the ports section of the project's .aec.json (source of truth for that project)
• Across projects: AEC's registry, maintained by aec ports (never edit it by hand)
• Updates: Declare a port in .aec.json and register it before adding a service or changing a port

Port Allocation Rules

Port Registration Requirements

• MANDATORY: Declare every service port in the project's .aec.json and register it with aec ports register
• BEFORE: Adding new services or changing existing ports, run aec ports check
• VERIFY: Resolve every conflict aec ports check reports before committing
• UPDATE: After a port change, run aec ports unregister then aec ports register (register only adds)

Port Range Allocations

• System Ports: 1-1023 (reserved for system)
• User Ports: 1024-49151 (available for projects)
• Dynamic Ports: 49152-65535 (OS-assigned)
• Testing Range: 5000-5999 (test containers)
• Development Range: 3000-3999 (dev servers)
• Database Range: 5400-5499 (databases)
• Cache Range: 6300-6399 (Redis, Memcached)
• Webhook Range: 34000-34999 (test webhooks)

Declaring ports in .aec.json

{
  "ports": {
    "web": { "port": 3000, "protocol": "http", "description": "Next.js dev server" },
    "db":  { "port": 5432, "protocol": "tcp",  "description": "Postgres" }
  }
}

Name each entry for the service it serves; protocol and description are shown by aec ports list.