After the template deployment was successful, we were unsure of the specific purposes and access points of each address.

[sc-source]

👋 Context
I have recently experimented with several agentseek templates . After successfully deploying multiple of them, I noticed that the terminal consistently outputs a list of environment variables and localhost addresses.

❓ The Problem
As a new user, I am completely unsure about the specific meaning of these addresses and which one I should open in my browser to actually use the application.

BUB_AG_UI_AGENT_URL=http://127.0.0.1:8088/agent
VITE_COPILOTKIT_RUNTIME_PROXY=http://127.0.0.1:4000
VITE_BUB_AG_UI_URL=http://127.0.0.1:8088
VITE_LANGGRAPH_API_URL=http://127.0.0.1:5174
Phoenix : http://127.0.0.1:6006
studio：http://127.0.0.1:2024
FRONTEND_PORT=5173 
and 5174

I have the following questions that need clarification:

Main Entry Point: Which URL should I visit to start using the Agent? Is it port 5173 or 8088? What is the functional difference between them?
Purpose of Other Ports: Are ports 4000, 5174, and 6006 (Phoenix) for internal use only, or should users access them? What role does each play?
Missing Guidance: The current output simply lists variables and address without providing a clear "Next Step" (e.g., "Open http://... to start chatting"). This causes repeated confusion when trying different templates.

[webup]

Thanks — the direct answer is: open the service described as the Application or Frontend, not every URL printed by the template.

For the defaults in the examples above:

Address	What it is	Open directly?
http://127.0.0.1:5173 or :5174	The browser application. Bub defaults to 5173; several LangGraph/DeepAgents templates default to 5174.	Yes. This is normally the next step.
http://127.0.0.1:8088/agent	The AG-UI protocol endpoint used by the frontend/runtime to communicate with the agent.	No normal web page; use it as an integration endpoint. See the AG-UI overview.
http://127.0.0.1:4000 (or /api/copilotkit)	The CopilotKit runtime/proxy used by the frontend.	Normally no; it is supporting application infrastructure. See CopilotKit architecture.
http://127.0.0.1:2024	The local LangGraph Agent Server/API.	Not the main app. Open /docs for API docs or use LangSmith Studio to interact with/debug the agent. The local-server guide explains all three URLs.
http://127.0.0.1:6006	Phoenix tracing and observability UI, when that optional service has been started.	Yes, for debugging/observability rather than normal app use. See Phoenix documentation.
mysql://...	OceanBase seekdb connection endpoint.	No; database clients and services consume it.

VITE_* entries are frontend configuration values, not a list of pages to open. Also, outputs from different generated projects should not be combined: each template can choose its own ports. In the standard LangGraph templates, the backend port defaults to 2024 and the frontend port commonly defaults to 5174; if VITE_LANGGRAPH_API_URL points to 5174, confirm that the project was intentionally configured that way and that it is not the frontend port.

The current workaround is to use agentseek info for declared endpoints, agentseek doctor --live for health, and the generated project's .agentseek/lifecycle.toml/README for meaning. But the issue is valid: current lifecycle v1 does not distinguish a browser entry point from an API, protocol, database, or internal dependency, so it cannot produce a reliable “Next step.”

Proposed contract

I audited all current lifecycle-bearing templates (11 registered templates plus the quarantined bub/contextseek template). A batch migration is feasible with a compact lifecycle v2 model:

version = 2
guide = "README.md"

[services.frontend]
url = "http://127.0.0.1:${FRONTEND_PORT}"
kind = "web"
display = "default"
primary = true
description = "Browser application for this template."

[services.backend]
url = "http://127.0.0.1:${BACKEND_PORT}"
kind = "api"
display = "advanced"
description = "LangGraph API used by the frontend."
tech = "langgraph"
links = { docs = "https://docs.langchain.com/oss/python/langgraph/overview", api_docs = "http://127.0.0.1:${BACKEND_PORT}/docs", studio = "https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:${BACKEND_PORT}" }

The important semantics are:

• kind says how the endpoint is used: web, api, protocol, database, or other.
• primary identifies the one normal first entry point.
• display only controls presentation: default, advanced, or hidden. It is not authentication, authorization, network exposure, or a security boundary.
• description, optional tech, and typed links explain supporting services and provide quick references.
• Matching IDs stay compact: processes.backend implicitly provides services.backend, and checks.backend implicitly checks it. Only exceptions need provides, service, starts, or stops annotations.

For Desktop and other tools, the authored TOML should be normalized into an explicit, versioned contract rather than asking clients to parse terminal text:

• agentseek info --json: deterministic declared topology, references, providers, checks, tasks, and safe actions such as open_url, copy_endpoint, open_reference, start_dev, and run_task.
• agentseek doctor [--live] --json: runtime/static results with explicit not_run, pass, or fail states.
• Lifecycle v1 remains supported, but its missing semantics are returned as unknown/incomplete and no actions are guessed from names or port numbers.
• JSON never includes environment values/defaults or raw process/task commands; unsafe URLs are rejected in v2 and omitted with warnings when projecting v1.
• Existing human-readable output remains unchanged until a separate change uses the same normalized model to print an accurate “Open …” next step.

The template audit found only a few explicit exceptions: Bub's frontend process/check provides the app service, the hybrid template's custom_routes check belongs to backend, Phoenix can be task-started, and langchain/default has one stack process that provides five services. Those fit the annotations above without template-specific heuristics.

This keeps the template file small while giving both people and Desktop unambiguous, reusable service metadata.

[sc-source]

Hi @webup,

Thank you for the detailed explanation! This clears up my confusion completely.

Key Takeaways for me:

I should focus on the Frontend URL (e.g., :5173 for Bub, :5174 for LangGraph) as the main entry point.
The other ports (:8088, :4000, :2024, etc.) are internal APIs or infrastructure services that don't need direct browser access.
The VITE_* variables are configuration values, not endpoints to visit.
Feedback on the Proposed Solution:
The proposed Lifecycle v2 contract sounds excellent! Explicitly defining kind, primary, and display semantics will significantly improve the Developer Experience (DX).

Having a clear primary = true flag will eliminate the guesswork for new users.
The idea of using agentseek info --json to provide deterministic topology data is very promising for both CLI tools and potential GUI integrations.
I'm glad to hear that a batch migration is feasible. Looking forward to seeing this implemented in future releases. Until then, I'll make sure to check the specific template's README for the correct frontend port.

Thanks again for the quick and thorough response!

[webup]

Shipped in AgentSeek v0.1.0 🎉

The lifecycle v2 proposal above is now implemented across all 11 published templates. A Desktop or other integration should run these commands inside a generated project and consume the JSON document instead of parsing terminal prose:

agentseek info --json
agentseek doctor --live --json

Both commands return public JSON schema version 1. info exposes normalized services, providers, checks, tasks, reference links, and safe actions. In particular, primary, kind, and display distinguish the normal browser entry point from APIs, protocol endpoints, databases, and supporting infrastructure; an open_url action is the explicit signal that a service can be opened directly. doctor --live --json adds typed runtime results without changing that topology.

Lifecycle v1 projects are still accepted. Because v1 does not carry the new semantics, their JSON is deliberately conservative: metadata_complete is false, unknown relationships remain unknown, and AgentSeek does not guess actions from names or port numbers.

Templates are now published independently in agentseek-ai/agentseek-templates v0.1.0. The default CLI embeds an immutable catalog lock, so listing works offline and named generation fetches only the exact protected catalog commit recorded by the installed AgentSeek release. AgentSeek v0.1.0 also supports an explicit catalog repository pinned to a full commit:

agentseek create \
  --template-repo https://github.com/agentseek-ai/agentseek-templates.git \
  --checkout 494863bc1b9aab19f9885d716c03ce654fb26014 \
  --list-templates

The same repository-plus-commit coordinate is used for list, filter, describe, and create operations; failures do not silently fall back to another catalog.

Quick references:

• Lifecycle v2 Service Discovery
• CLI reference
• Template catalog and repository override
• Versioned catalog boundary ADR

The release gate also exercised the published AgentSeek 0.0.1 through 0.0.5 clients against their lifecycle v1 templates, so this cutover preserves the existing release lines while new 0.1.0 projects use lifecycle v2.