Getting Started

Getting Started

Goal: a working development environment in 15 minutes.

1. Requirements

Tool	Version	Check
Docker + Compose	v2+	docker compose version
Git	2.40+	git --version
Python	3.11+	python3 --version
JDK	21	java -version
Maven	3.9+	mvn -v
make	—	make --version

Quick install for macOS:

brew install --cask docker
brew install git python@3.11 openjdk@21 maven make gh

2. Clone the repo and bring it up

git clone https://github.com/canquesse/agentlens.git
cd agentlens
cp .env.example .env
make up

3. Verify

curl http://localhost:8080/health   # {"status":"ok","service":"control-plane"}
curl http://localhost:8000/health   # {"status":"ok"}

Interfaces:

What	Where
agent-runtime OpenAPI	http://localhost:8000/docs
control-plane OpenAPI	http://localhost:8080/swagger-ui.html
Actuator health	http://localhost:8080/actuator/health
PostgreSQL	make db-shell

4. Run the tests

make test    # Python + Java
make lint

5. Local development (no containers, faster loop)

# Keep only the database in a container
docker compose up -d postgres

# Terminal 1 — Python
cd agent-runtime
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
POSTGRES_HOST=localhost uvicorn app.main:app --reload

# Terminal 2 — Java
cd control-plane
POSTGRES_HOST=localhost mvn spring-boot:run

Common problems

Symptom	Cause	Fix
port already allocated	5432/8000/8080 in use	find it with lsof -i :5432, stop it or change the port in compose
Java service won't start with a Flyway error	Schema left in a broken state	make clean && make up (data is lost)
make up hangs forever	Docker Desktop is off	Start Docker
Python change not reflected	Container is using an old image	make rebuild
mvn can't download dependencies	Network / proxy	Check ~/.m2/settings.xml

Your first contribution

1. Pick an issue labeled good first issue
2. Read the Workflow page
3. Open a branch, do the work, send a PR