Port and Instance Lifecycle

Unified Rule

• Agent ports are allocated by console.
• city agent start/restart does not require users to manage ports manually.
• service and plugin commands resolve target agent first, then endpoint.

Runtime Roles

console

• Maintains ~/.downcity/console/agents.json
• Starts/stops/restarts agent daemons
• Allocates agent ports

agent

• One project maps to one daemon
• Runtime HTTP APIs include /api/services/* and /api/plugins/*
• Debug metadata is persisted to .downcity/.debug

service / plugin

• city service ... calls service routes
• city plugin ... calls plugin routes
• both are dispatched in the target runtime

Agent Port Allocation

1. Validate console is running
2. Validate project files
3. Allocate an available port
4. Start daemon
5. Persist debug metadata
6. Upsert console registry

Endpoint Resolution

For runtime API calls:

1. explicit CLI --host / --port
2. DC_SERVER_HOST/PORT
3. DC_CTX_SERVER_HOST/PORT
4. daemon metadata
5. default 127.0.0.1:5314

Recommendations

• In multi-agent scenarios, prefer city service ... --agent <name>. Plugin actions run locally against the selected project path.
• Do not keep stale DC_SERVER_PORT in your shell profile.
• If runtime status is abnormal, run city agent doctor --fix and inspect daemon logs.