Port and Instance Lifecycle

Unified Rule

• Agent ports are allocated by console.
• studio agent start/restart does not require users to manage ports manually.
• plugin commands resolve the target agent first, then the 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/plugins/list, /api/plugins/catalog, and /api/plugins/*
• Debug metadata is persisted to .downcity/.debug

plugin endpoints

• studio 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 plugin API calls:

1. explicit CLI --host / --port
2. DC_CITY_HOST/DC_CITY_PORT
3. daemon metadata
4. default 127.0.0.1:5314

Recommendations

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