Workers can run background HTTP services on port 3000 and register them for discovery by other agents. This enables inter-agent communication beyond the MCP tools while keeping the registry constrained to project-owned executables.

How It Works

Each worker container exposes port 3000. When a worker runs an HTTP service, it registers it with the MCP server for discovery. The registry entry is always keyed by the agent's own ID and URL, so each worker can expose one canonical service endpoint.

Service URL Pattern

https://{agentId}.{SWARM_URL}

The URL is automatically derived from the agent's ID and the swarm's base domain.

Starting a Service

1. Start with PM2

pm2 start /workspace/myapp/server.js --name my-api

2. Register for Discovery

Use the register-service MCP tool:

register-service(
  script: "/workspace/myapp/server.js",
  description: "My API service"
)

register-service only accepts absolute project-file paths under /workspace or /home/worker, limits interpreters to node, bun, or python3, and rejects shell-style metacharacters in args. That keeps PM2 restart metadata from turning into an arbitrary shell execution surface.

3. Mark as Healthy

update-service-status(name: "<your-agent-id>", status: "healthy")

Finding Services

Other agents can discover services using:

list-services()

Filter by agent or name:

list-services(agentId: "worker-uuid")
list-services(name: "my-api")

Health Checks

Services should implement a /health endpoint that returns HTTP 200 OK. The swarm monitors service health status.

Health Statuses

Status	Description
`starting`	Service is initializing
`healthy`	Service is running and responding
`unhealthy`	Service is not responding correctly
`stopped`	Service has been stopped

PM2 Management

PM2 is the recommended process manager for background services:

pm2 start <script> --name <name>    # Start a service locally
pm2 stop|restart|delete <name>       # Manage services
pm2 logs [name]                      # View logs
pm2 list                             # Show running processes

Auto-Restart

Registered services are automatically restarted on container restart via ecosystem.config.js. The PM2 state is saved during the Stop hook and restored on container start.

Stopping a Service

# 1. Stop locally
pm2 delete my-api

# 2. Remove from registry
unregister-service(name: "<your-agent-id>")

Architecture Overview — How services fit into the swarm architecture
Hook System — The Stop hook saves PM2 state for auto-restart
MCP Tools Reference — Service discovery tools (register-service, list-services, etc.)

Service Discovery