feat(cli): add --image-uri flag for self-hosted deployments (#8482)

Adds `--image-uri <uri>` to `langgraph deploy` so self-hosted LangSmith
customers can build, push, and deploy in one command without needing to
script the three steps manually.

When `--image-uri` is provided the CLI:
- Builds the image tagged to the provided URI (same Docker build path as
the local build flow)
- Pushes using whatever Docker credentials are already in the
environment (e.g. WIF, `aws ecr get-login-password`) — no auth handling
in the CLI
- PATCHes the deployment with `source_revision_config.image_uri` (no
`revision_source`, which the self-hosted control plane rejects for
`external_docker` deployments)

Also fixes two self-hosted-specific issues uncovered during testing:
- `LANGSMITH_ENDPOINT` is now used as a fallback when
`LANGGRAPH_HOST_URL` isn't set — the CLI strips the `/api/v1` path and
appends `/api-host` to reach the control plane
- The httpx client now builds full URLs via string concatenation rather
than relying on httpx base_url merging, which silently dropped the
`/api-host` path prefix when paths started with `/`
- The "Check status at" URL after a deploy now correctly points to the
self-hosted LangSmith UI instead of `smith.langchain.com`

**How did you verify your code works?**
Tested end-to-end against a self-hosted LangSmith instance using ECR as
the registry. `langgraph deploy --image-uri <ecr-uri>` successfully
built, pushed, and triggered a deployment revision. Confirmed the
existing SaaS flow (`langgraph deploy` without `--image-uri`) is
unaffected — the new flag is opt-in and the `LANGSMITH_ENDPOINT`
fallback only activates when `LANGGRAPH_HOST_URL` is unset and
`LANGSMITH_ENDPOINT` is present.

---------

Co-authored-by: Hari Dhanushkodi <hari-dhanushkodi@users.noreply.github.com>
Co-authored-by: open-swe[bot] <open-swe@users.noreply.github.com>
Co-authored-by: Hugo Durand <hugo.durand@langchain.dev>

libs/cli/langgraph_cli/exec.py

@@ -1,12 +1,18 @@
 import asyncio
 import signal
 import sys
-from collections.abc import Callable
+from collections.abc import Callable, Coroutine
 from contextlib import contextmanager
-from typing import cast
+from typing import Any, Protocol, TypeVar, cast
 
 import click.exceptions
 
+_T = TypeVar("_T")
+
+
+class CommandRunner(Protocol):
+    def run(self, coro: Coroutine[Any, Any, _T]) -> _T: ...
+
 
 @contextmanager
 def Runner():

libs/cli/langgraph_cli/host_backend.py

@@ -2,11 +2,86 @@
 
 from __future__ import annotations
 
-from typing import Any
+from dataclasses import dataclass
+from typing import Any, Literal
+from urllib.parse import urlparse
 
 import click
 import httpx
 
+CLOUD_CONTROL_PLANE_URL = "https://api.host.langchain.com"
+CLOUD_DASHBOARD_URL = "https://smith.langchain.com"
+CLOUD_DOMAIN = "langchain.com"
+CLOUD_API_HOST = "api.smith.langchain.com"
+CLOUD_CONTROL_PLANE_HOST = "api.host.langchain.com"
+CLOUD_DASHBOARD_HOST = "smith.langchain.com"
+CONTROL_PLANE_PATH = "/api-host"
+LANGSMITH_API_PATHS = ("/api/v1", "/api")
+LOCAL_HOSTNAMES = ("localhost", "127.0.0.1")
+SourceName = Literal["internal_docker", "internal_source", "external_docker"]
+
+
+@dataclass(frozen=True, slots=True)
+class ControlPlaneEndpoints:
+    control_plane_url: str
+    dashboard_url: str
+
+    @classmethod
+    def resolve(
+        cls, host_url: str | None, langsmith_endpoint: str | None
+    ) -> ControlPlaneEndpoints:
+        if host_url:
+            return cls.from_control_plane_url(host_url)
+        if langsmith_endpoint:
+            return cls.from_langsmith_endpoint(langsmith_endpoint)
+        return cls(CLOUD_CONTROL_PLANE_URL, CLOUD_DASHBOARD_URL)
+
+    @classmethod
+    def from_control_plane_url(cls, url: str) -> ControlPlaneEndpoints:
+        control_plane_url = url.rstrip("/")
+        hostname = urlparse(control_plane_url).hostname or ""
+        if control_plane_url.endswith(CONTROL_PLANE_PATH):
+            return cls(control_plane_url, control_plane_url[: -len(CONTROL_PLANE_PATH)])
+        if hostname in LOCAL_HOSTNAMES:
+            return cls(control_plane_url, control_plane_url)
+        return cls(control_plane_url, _cloud_dashboard_for(hostname))
+
+    @classmethod
+    def from_langsmith_endpoint(cls, endpoint: str) -> ControlPlaneEndpoints:
+        parsed = urlparse(endpoint.rstrip("/"))
+        hostname = parsed.hostname or ""
+        if _is_cloud_host(hostname):
+            return cls.from_control_plane_url(
+                f"https://{_cloud_control_plane_host_for(hostname)}"
+            )
+        root = f"{parsed.scheme}://{parsed.netloc}{_without_api_path(parsed.path)}"
+        return cls(f"{root}{CONTROL_PLANE_PATH}", root)
+
+
+def _is_cloud_host(hostname: str) -> bool:
+    return hostname == CLOUD_DOMAIN or hostname.endswith(f".{CLOUD_DOMAIN}")
+
+
+def _cloud_control_plane_host_for(langsmith_api_host: str) -> str:
+    if langsmith_api_host.endswith(f".{CLOUD_API_HOST}"):
+        region = langsmith_api_host[: -len(CLOUD_API_HOST)]
+        return f"{region}{CLOUD_CONTROL_PLANE_HOST}"
+    return CLOUD_CONTROL_PLANE_HOST
+
+
+def _cloud_dashboard_for(control_plane_host: str) -> str:
+    if control_plane_host.endswith(f".{CLOUD_CONTROL_PLANE_HOST}"):
+        region = control_plane_host[: -len(CLOUD_CONTROL_PLANE_HOST) - 1]
+        return f"https://{region}.{CLOUD_DASHBOARD_HOST}"
+    return CLOUD_DASHBOARD_URL
+
+
+def _without_api_path(path: str) -> str:
+    for api_path in LANGSMITH_API_PATHS:
+        if path.endswith(api_path):
+            return path[: -len(api_path)]
+    return path
+
 
 class HostBackendError(click.ClickException):
     """Raised when the host backend returns an error response."""
@@ -24,10 +99,11 @@ class HostBackendClient:
         base_url: str,
         api_key: str,
         tenant_id: str | None = None,
+        *,
+        transport: httpx.BaseTransport | None = None,
     ):
         if not base_url:
             raise click.UsageError("Host backend URL is required")
-        transport = httpx.HTTPTransport(retries=3)
         headers: dict[str, str] = {
             "X-Api-Key": api_key,
             "Accept": "application/json",
@@ -38,10 +114,17 @@ class HostBackendClient:
         self._client = httpx.Client(
             base_url=self._base_url,
             headers=headers,
-            transport=transport,
+            transport=transport or httpx.HTTPTransport(retries=3),
             timeout=30,
         )
 
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    def set_tenant(self, tenant_id: str) -> None:
+        self._client.headers["X-Tenant-ID"] = tenant_id
+
     def _request(
         self,
         method: str,
@@ -72,21 +155,19 @@ class HostBackendClient:
 
     def create_deployment(
         self,
+        *,
         name: str,
-        deployment_type: str,
-        source: str,
-        config_path: str | None = None,
+        source: SourceName,
+        source_config: dict[str, object],
+        source_revision_config: dict[str, object],
         secrets: list[dict[str, str]] | None = None,
     ) -> dict[str, Any]:
-        """Create a deployment."""
         payload: dict[str, Any] = {
             "name": name,
             "source": source,
-            "source_config": {"deployment_type": deployment_type},
-            "source_revision_config": {},
+            "source_config": source_config,
+            "source_revision_config": source_revision_config,
         }
-        if source == "internal_source" and config_path:
-            payload["source_revision_config"]["langgraph_config_path"] = config_path
         if secrets is not None:
             payload["secrets"] = secrets
         return self._request("POST", "/v2/deployments", payload)
@@ -121,22 +202,21 @@ class HostBackendClient:
         self,
         deployment_id: str,
         image_uri: str,
+        *,
+        revision_source: SourceName | None,
         secrets: list[dict[str, str]] | None = None,
         tracked_packages: list[str] | None = None,
     ) -> dict[str, Any]:
         payload: dict[str, Any] = {
-            "revision_source": "internal_docker",
             "source_revision_config": {"image_uri": image_uri},
         }
+        if revision_source is not None:
+            payload["revision_source"] = revision_source
         if tracked_packages:
             payload["tracked_packages"] = tracked_packages
         if secrets is not None:
             payload["secrets"] = secrets
-        return self._request(
-            "PATCH",
-            f"/v2/deployments/{deployment_id}",
-            payload,
-        )
+        return self._request("PATCH", f"/v2/deployments/{deployment_id}", payload)
 
     def update_deployment_internal_source(
         self,

libs/cli/langgraph_cli/image_reference.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+
+DIGEST_SEPARATOR = "@sha256:"
+DIGEST_MARKER = "@"
+TAG_SEPARATOR = ":"
+PATH_SEPARATOR = "/"
+
+
+@dataclass(frozen=True, slots=True)
+class ImageReference:
+    repository: str
+    tag: str | None = None
+
+    @classmethod
+    def parse(cls, reference: str) -> ImageReference:
+        if DIGEST_MARKER in reference:
+            raise ValueError(f"{reference!r} carries a digest and cannot be tagged")
+        path_start = reference.rfind(PATH_SEPARATOR) + 1
+        name, separator, tag = reference[path_start:].partition(TAG_SEPARATOR)
+        if not separator:
+            return cls(reference)
+        return cls(reference[:path_start] + name, tag)
+
+    def with_tag(self, tag: str) -> ImageReference:
+        return replace(self, tag=tag)
+
+    def matches_digest(self, repo_digest: str) -> bool:
+        return repo_digest.startswith(f"{self.repository}{DIGEST_SEPARATOR}")
+
+    def __str__(self) -> str:
+        if self.tag is None:
+            return self.repository
+        return f"{self.repository}{TAG_SEPARATOR}{self.tag}"