fix(server): separate compose host port overrides from runtime ports

README.md

@@ -66,12 +66,23 @@ curl -L https://raw.githubusercontent.com/agentcontrol/agent-control/refs/heads/
 This starts PostgreSQL and Agent Control at `http://localhost:8000`, including
 the UI/dashboard.
 
+To override the exposed host ports, set `AGENT_CONTROL_SERVER_HOST_PORT` and/or
+`AGENT_CONTROL_DB_HOST_PORT` before starting Compose. Example:
+
+```bash
+export AGENT_CONTROL_SERVER_HOST_PORT=18000
+export AGENT_CONTROL_DB_HOST_PORT=15432
+curl -L https://raw.githubusercontent.com/agentcontrol/agent-control/refs/heads/main/docker-compose.yml | docker compose -f - up -d
+```
+
 Verify it is up:
 
 ```bash
 curl http://localhost:8000/health
 ```
 
+If you changed `AGENT_CONTROL_SERVER_HOST_PORT`, use that port in the health check URL.
+
 ### 2. Install the SDK
 
 Run this in your agent project directory.

docker-compose.dev.yml

@@ -5,6 +5,7 @@
 #
 # Usage:
 #   docker compose -f docker-compose.dev.yml up -d
+#   AGENT_CONTROL_DB_HOST_PORT=15432 docker compose -f docker-compose.dev.yml up -d
 #   cd server && uvicorn main:app --reload
 #   OR
 #   make server-run  (handles this automatically)
@@ -16,7 +17,7 @@ services:
     image: postgres:16-alpine
     container_name: agent_control_postgres
     ports:
-      - "5432:5432"
+      - "${AGENT_CONTROL_DB_HOST_PORT:-5432}:5432"
     environment:
       POSTGRES_DB: agent_control
       POSTGRES_USER: agent_control

docker-compose.yml

@@ -2,6 +2,7 @@
 #
 # Quick Start:
 #   docker compose up -d
+#   AGENT_CONTROL_SERVER_HOST_PORT=18000 AGENT_CONTROL_DB_HOST_PORT=15432 docker compose up -d
 #
 # Services:
 #   - PostgreSQL database (port 5432)
@@ -21,7 +22,7 @@ services:
     image: postgres:16-alpine
     container_name: agent_control_postgres
     ports:
-      - "5432:5432"
+      - "${AGENT_CONTROL_DB_HOST_PORT:-5432}:5432"
     environment:
       POSTGRES_DB: agent_control
       POSTGRES_USER: agent_control
@@ -40,7 +41,7 @@ services:
     image: galileoai/agent-control-server:latest
     container_name: agent_control_server
     ports:
-      - "8000:8000"
+      - "${AGENT_CONTROL_SERVER_HOST_PORT:-8000}:8000"
     environment:
       # Database connection (uses Docker service name 'postgres')
       # Use postgresql+psycopg:// (supports both sync migrations and async app code)

server/Makefile

@@ -7,14 +7,19 @@ UP ?= head
 DOWN ?= -1
 SHOW ?= head
 STAMP ?= head
+AGENT_CONTROL_HOST ?= 0.0.0.0
+AGENT_CONTROL_PORT ?= 8000
+AGENT_CONTROL_DB_PORT ?= 5432
+AGENT_CONTROL_DB_HOST_PORT ?= $(AGENT_CONTROL_DB_PORT)
 
 TEST_DB ?= agent_control_test
 TEST_DB_ENV := env -u AGENT_CONTROL_DB_URL -u DATABASE_URL -u DB_URL AGENT_CONTROL_DB_HOST=localhost AGENT_CONTROL_DB_PORT=5432 AGENT_CONTROL_DB_USER=agent_control AGENT_CONTROL_DB_PASSWORD=agent_control AGENT_CONTROL_DB_DATABASE=$(TEST_DB) AGENT_CONTROL_DB_DRIVER=psycopg
 .PHONY: help run start-dependencies test migrate alembic-migrate alembic-revision alembic-upgrade alembic-downgrade alembic-current alembic-history alembic-heads alembic-show alembic-stamp
 
 help:
 	@echo "Available targets:"
-	@echo "  run                          - start FastAPI server (reload)"
+	@echo "  run                          - start FastAPI server (reload; honors AGENT_CONTROL_HOST/AGENT_CONTROL_PORT)"
+	@echo "                                 local Postgres host mapping defaults to AGENT_CONTROL_DB_PORT"
 	@echo "  start-dependencies           - docker compose up -d (start local dependencies)"
 	@echo "  test                         - run server tests (uses $(TEST_DB_ENV))"
 	@echo "  migrate                      - run database migrations (alembic upgrade head)"
@@ -56,7 +61,7 @@ alembic-stamp:
 	$(ALEMBIC) stamp $(STAMP)
 
 start-dependencies:
-	docker compose -f ../docker-compose.dev.yml up -d
+	AGENT_CONTROL_DB_HOST_PORT=$(AGENT_CONTROL_DB_HOST_PORT) docker compose -f ../docker-compose.dev.yml up -d
 	@echo "Waiting for PostgreSQL to be ready..."
 	@until docker compose -f ../docker-compose.dev.yml exec -T postgres pg_isready -U agent_control -d agent_control > /dev/null 2>&1; do \
 		sleep 1; \
@@ -67,4 +72,4 @@ test:
 	$(TEST_DB_ENV) uv run --package agent-control-server pytest --cov=src --cov-report=xml:../coverage-server.xml -q
 
 run: start-dependencies migrate
-	uv run --package agent-control-server uvicorn agent_control_server.main:app --reload
+	uv run --package agent-control-server uvicorn agent_control_server.main:app --reload --host $(AGENT_CONTROL_HOST) --port $(AGENT_CONTROL_PORT)

server/README.md

@@ -21,6 +21,12 @@ make server-run
 
 Server runs on http://localhost:8000. The UI expects this base URL by default.
 
+To use non-default local ports with `make server-run`, export
+`AGENT_CONTROL_PORT` for the server listen port. If you also want the local
+Postgres container exposed on a different host port, set
+`AGENT_CONTROL_DB_HOST_PORT` and point the server at the same value with
+`AGENT_CONTROL_DB_PORT`.
+
 ## Configuration
 
 Server configuration is driven by environment variables (database, auth, observability, evaluators). For the full list and examples, see the docs.