Run Agents (Java)¶

🐍 Looking for Python? See Python Run Agents | 📘 Looking for TypeScript? See TypeScript Run Agents

Start Java agents with meshctl start

Basic Usage (Recommended)¶

# Start a Java agent (point to the project directory containing pom.xml)
meshctl start hello/

meshctl detects the pom.xml, builds via Maven, and starts the agent. It also starts the registry automatically if not already running.

Debug Mode¶

Enable verbose logging:

meshctl start --debug hello/

# Or set specific log level
meshctl start --log-level DEBUG hello/

# Available levels: TRACE, DEBUG, INFO, WARN, ERROR

Hot Reload¶

Auto-rebuild and restart on code changes:

meshctl start -w hello/
meshctl start --watch hello/

Background Mode¶

Run agents in the background (detached):

# Start in background
meshctl start -d hello/

# View logs
meshctl logs greeter -f

# Stop background agents
meshctl stop --all

Multiple Agents¶

# Start multiple agents at once (mixed languages supported)
meshctl start hello/ employee-service/ ../typescript/calculator.ts

Environment Variables¶

Share configuration across agents:

# Load from .env file
meshctl start --env-file .env hello/

# Or pass individual variables
meshctl start --env OPENAI_API_KEY=sk-... hello/

Registry Options¶

# Start registry only (no agents)
meshctl start --registry-only

# Use custom registry port
meshctl start --registry-port 9000 hello/

# Connect to external registry
meshctl start --registry-url http://remote:8000 hello/

Common Patterns¶

# Development: hot reload + debug
meshctl start -w --debug hello/

# CI/Testing: background + quiet
meshctl start -d --quiet hello/

# Production-like: custom registry
meshctl start --registry-url http://registry:8000 hello/

Alternative: Maven / JAR / IDE¶

You can also run agents directly — they register with the mesh the same way and appear in meshctl list/status/call:

# 1. Start the registry separately
meshctl start --registry-only

# 2a. Run via Maven
cd hello/
mvn spring-boot:run

# 2b. Or run the JAR directly
cd hello/
mvn package -DskipTests
java -jar target/hello-1.0.0-SNAPSHOT.jar

# 2c. Or run from your IDE (IntelliJ, Eclipse, VS Code)
#     Just run the main class with Spring Boot run configuration

meshctl vs direct

All approaches register with the mesh identically. meshctl start adds convenience flags (--debug, --watch, --env-file, --detach) that simplify the dev workflow.

All Options¶

meshctl start --help

Key flags:

Flag	Description
`-w, --watch`	Hot reload on file changes
`-d, --detach`	Run in background
`--debug`	Enable debug mode
`--log-level`	Set log level (TRACE/DEBUG/INFO/WARN/ERROR)
`--env-file`	Load environment from file
`--env`	Set individual env var
`--registry-only`	Start registry without agents
`--registry-port`	Registry port (default: 8000)

Next Steps¶

Continue to Inspect the Mesh ->