feat(cli): add remote build support for langgraph deploy (#7234)

**Description:** 

 - extend host_backend client with remote build support
- refactored `cli.py` for better clarity
- update tests

libs/cli/langgraph_cli/archive.py

@@ -0,0 +1,161 @@
+"""Create a tarball of project source for remote builds."""
+
+import os
+import pathlib
+import tarfile
+import tempfile
+from contextlib import contextmanager
+
+import click
+import pathspec
+
+from langgraph_cli.config import Config, _assemble_local_deps
+
+_WARN_SIZE = 50 * 1024 * 1024  # 50 MB
+_MAX_SIZE = 200 * 1024 * 1024  # 200 MB
+
+_ALWAYS_EXCLUDE = [
+    "__pycache__/",
+    ".git/",
+    ".venv/",
+    "venv/",
+    "node_modules/",
+    ".tox/",
+    ".mypy_cache/",
+]
+
+
+def _build_ignore_spec(directory: pathlib.Path) -> pathspec.PathSpec:
+    """Build a PathSpec combining built-in exclusions with .dockerignore and .gitignore.
+
+    Always excludes common non-source directories (_ALWAYS_EXCLUDE).  On top of
+    that, patterns from .dockerignore and .gitignore (if present) are merged in.
+    """
+    lines: list[str] = list(_ALWAYS_EXCLUDE)
+    for name in (".dockerignore", ".gitignore"):
+        ignore_file = directory / name
+        if ignore_file.is_file():
+            lines.extend(ignore_file.read_text(encoding="utf-8").splitlines())
+    return pathspec.PathSpec.from_lines("gitwildmatch", lines)
+
+
+def _tar_filter(tarinfo: tarfile.TarInfo) -> tarfile.TarInfo | None:
+    """Strip symlinks, hardlinks, and traversal paths from archive."""
+    if tarinfo.issym() or tarinfo.islnk():
+        return None
+    if ".." in tarinfo.name.split("/"):
+        return None
+    return tarinfo
+
+
+def _add_directory(
+    tar: tarfile.TarFile,
+    source_dir: pathlib.Path,
+    arcname_prefix: str | None,
+    ignore_spec: pathspec.PathSpec,
+) -> None:
+    """Recursively add a directory to the tarball under the given prefix.
+
+    If arcname_prefix is None, files are added at the archive root.
+    Paths matching ignore_spec are excluded.
+    """
+    for root, dirs, files in os.walk(source_dir):
+        rel_root = os.path.relpath(root, source_dir).replace(os.sep, "/")
+        dirs[:] = [
+            d
+            for d in dirs
+            if not ignore_spec.match_file(
+                f"{rel_root}/{d}/" if rel_root != "." else f"{d}/"
+            )
+        ]
+        for f in files:
+            full_path = os.path.join(root, f)
+            rel = os.path.relpath(full_path, source_dir).replace(os.sep, "/")
+            if ignore_spec.match_file(rel):
+                continue
+            arcname = f"{arcname_prefix}/{rel}" if arcname_prefix else rel
+            info = tar.gettarinfo(full_path, arcname=arcname)
+            filtered = _tar_filter(info)
+            if filtered is None:
+                continue
+            with open(full_path, "rb") as fobj:
+                tar.addfile(filtered, fobj)
+
+
+@contextmanager
+def create_archive(
+    config_path: pathlib.Path,
+    config: Config,
+):
+    """Context manager that creates a .tar.gz archive of the project source.
+
+    Uses _assemble_local_deps to discover local dependencies referenced in
+    langgraph.json, including those outside config.parent (monorepo case).
+
+    The archive preserves the real filesystem layout relative to the common
+    ancestor of config.parent and all external dependency directories, so that
+    relative references (e.g. `../shared-lib`) resolve correctly after
+    extraction.
+
+    Yields (archive_path, file_size, config_relative_path).  The temporary
+    directory holding the archive is cleaned up automatically on exit.
+    """
+    config_path = config_path.resolve()
+    context_dir = config_path.parent
+
+    local_deps = _assemble_local_deps(config_path, config)
+    extra_contexts = local_deps.additional_contexts or []
+
+    dirs_to_include = [context_dir] + list(extra_contexts)
+
+    common = context_dir
+    for d in extra_contexts:
+        common = pathlib.Path(os.path.commonpath([common, d]))
+
+    tmp_dir = tempfile.mkdtemp(prefix="langgraph-deploy-")
+    try:
+        archive_path = os.path.join(tmp_dir, "source.tar.gz")
+
+        added_dirs: set[str] = set()
+        with tarfile.open(archive_path, "w:gz") as tar:
+            for dir_path in dirs_to_include:
+                rel = dir_path.relative_to(common)
+                prefix = str(rel).replace(os.sep, "/") if str(rel) != "." else None
+                key = prefix or ""
+                if key in added_dirs:
+                    continue
+                added_dirs.add(key)
+                ignore_spec = _build_ignore_spec(dir_path)
+                _add_directory(
+                    tar, dir_path, arcname_prefix=prefix, ignore_spec=ignore_spec
+                )
+
+        file_size = os.path.getsize(archive_path)
+
+        config_rel = str(config_path.relative_to(common)).replace(os.sep, "/")
+
+        with tarfile.open(archive_path, "r:gz") as tar:
+            names = tar.getnames()
+            if config_rel not in names:
+                raise click.ClickException(
+                    f"Archive validation failed: {config_rel} not found in archive"
+                )
+
+        if file_size > _MAX_SIZE:
+            raise click.ClickException(
+                f"Source archive is {file_size / 1_048_576:.1f} MB, which exceeds the 200 MB limit. "
+                "Add large files to .dockerignore or .gitignore (model weights, data sets, etc.)."
+            )
+
+        if file_size > _WARN_SIZE:
+            click.secho(
+                f"   Warning: source archive is {file_size / 1_048_576:.1f} MB. "
+                "Consider adding large files to .dockerignore or .gitignore.",
+                fg="yellow",
+            )
+
+        yield archive_path, file_size, config_rel
+    finally:
+        import shutil
+
+        shutil.rmtree(tmp_dir, ignore_errors=True)

libs/cli/langgraph_cli/docker.py

@@ -1,10 +1,14 @@
+import copy
 import json
 import pathlib
+import platform
 import shutil
+from collections.abc import Callable, Sequence
 from typing import Literal, NamedTuple
 
 import click.exceptions
 
+import langgraph_cli.config
 from langgraph_cli.exec import subp_exec
 
 ROOT = pathlib.Path(__file__).parent.resolve()
@@ -45,6 +49,54 @@ def _parse_version(version: str) -> Version:
     )
 
 
+def can_build_locally() -> tuple[bool, str | None]:
+    """Return whether local deployment builds can run on this machine.
+
+    Checks:
+    - Docker binary is installed
+    - Docker daemon is running
+    - Buildx is available when cross-compilation is required (non-x86_64)
+    """
+    if shutil.which("docker") is None:
+        return (
+            False,
+            "Docker is required but not installed.\n"
+            "Install Docker Desktop: https://docs.docker.com/get-docker/",
+        )
+    try:
+        import subprocess
+
+        docker_info = subprocess.run(
+            ["docker", "info"],
+            capture_output=True,
+            timeout=10,
+        )
+        if docker_info.returncode != 0:
+            return (
+                False,
+                "Docker is installed but not running.\nStart Docker and try again.",
+            )
+
+        if platform.machine() != "x86_64":
+            buildx = subprocess.run(
+                ["docker", "buildx", "version"],
+                capture_output=True,
+                timeout=10,
+            )
+            if buildx.returncode != 0:
+                return (
+                    False,
+                    "Docker Buildx is required but not installed.\n"
+                    "Your machine architecture ("
+                    + platform.machine()
+                    + ") requires Buildx to cross-compile images for linux/amd64.\n"
+                    "Install Buildx: https://docs.docker.com/build/install-buildx/",
+                )
+        return True, None
+    except Exception:
+        return False, "Unable to verify local Docker build support."
+
+
 def check_capabilities(runner) -> DockerCapabilities:
     # check docker available
     if shutil.which("docker") is None:
@@ -276,3 +328,79 @@ def compose(
     )
     compose_str = dict_to_yaml(compose_content)
     return compose_str
+
+
+def build_docker_image(
+    runner,
+    set: Callable[[str], None],
+    config: pathlib.Path,
+    config_json: dict,
+    base_image: str | None,
+    api_version: str | None,
+    pull: bool,
+    tag: str,
+    passthrough: Sequence[str] = (),
+    install_command: str | None = None,
+    build_command: str | None = None,
+    docker_command: Sequence[str] | None = None,
+    extra_flags: Sequence[str] = (),
+    verbose: bool = True,
+):
+    """Build a Docker image from a LangGraph config."""
+    # pull latest images
+    if pull:
+        runner.run(
+            subp_exec(
+                "docker",
+                "pull",
+                langgraph_cli.config.docker_tag(config_json, base_image, api_version),
+                verbose=verbose,
+            )
+        )
+    set("Building...")
+    # apply options
+    args = [
+        "-f",
+        "-",  # stdin
+        "-t",
+        tag,
+    ]
+    # determine build context: use current directory for JS projects, config parent for Python
+    is_js_project = config_json.get("node_version") and not config_json.get(
+        "python_version"
+    )
+    # build/install commands only apply to JS projects for now
+    # without install/build command, JS projects will follow the old behavior
+    if is_js_project and (build_command or install_command):
+        build_context = str(pathlib.Path.cwd())
+    else:
+        build_context = str(config.parent)
+
+    # Deep copy to avoid mutating the caller's config (config_to_docker
+    # rewrites graph paths to container-internal paths in place).
+    config_json = copy.deepcopy(config_json)
+    stdin, additional_contexts = langgraph_cli.config.config_to_docker(
+        config_path=config,
+        config=config_json,
+        base_image=base_image,
+        api_version=api_version,
+        install_command=install_command,
+        build_command=build_command,
+        build_context=build_context,
+    )
+    # add additional_contexts
+    if additional_contexts:
+        for k, v in additional_contexts.items():
+            args.extend(["--build-context", f"{k}={v}"])
+    cmd = tuple(docker_command) if docker_command else ("docker", "build")
+    runner.run(
+        subp_exec(
+            *cmd,
+            *args,
+            *extra_flags,
+            *passthrough,
+            build_context,
+            input=stdin,
+            verbose=verbose,
+        )
+    )

libs/cli/langgraph_cli/helpers.py

@@ -1,59 +0,0 @@
-"""Helpers for the ``langgraph logs`` CLI command."""
-
-from __future__ import annotations
-
-from datetime import datetime, timezone
-
-import click
-
-from langgraph_cli.host_backend import HostBackendClient
-
-
-def resolve_deployment_id(
-    client: HostBackendClient,
-    deployment_id: str | None,
-    name: str | None,
-) -> str:
-    """Resolve a deployment ID from --deployment-id or --name."""
-    if deployment_id:
-        return deployment_id
-    if not name:
-        raise click.UsageError("Either --deployment-id or --name is required.")
-    existing = client.list_deployments(name_contains=name)
-    if isinstance(existing, dict):
-        for dep in existing.get("resources", []):
-            if isinstance(dep, dict) and dep.get("name") == name:
-                found_id = dep.get("id")
-                if found_id:
-                    return str(found_id)
-    raise click.ClickException(f"Deployment '{name}' not found.")
-
-
-def format_timestamp(ts) -> str:
-    """Convert a timestamp (epoch ms or string) to a readable string."""
-    if isinstance(ts, (int, float)):
-        dt = datetime.fromtimestamp(ts / 1000, tz=timezone.utc)
-        return dt.strftime("%Y-%m-%d %H:%M:%S")
-    return str(ts) if ts else ""
-
-
-def format_log_entry(entry: dict) -> str:
-    """Format a single log entry for display."""
-    ts = format_timestamp(entry.get("timestamp", ""))
-    level = entry.get("level", "")
-    message = entry.get("message", "")
-    if ts and level:
-        return f"[{ts}] [{level}] {message}"
-    elif ts:
-        return f"[{ts}] {message}"
-    return message
-
-
-def level_fg(level: str) -> str | None:
-    """Return click color for a log level."""
-    level_upper = level.upper() if level else ""
-    if level_upper in {"ERROR", "CRITICAL"}:
-        return "red"
-    if level_upper == "WARNING":
-        return "yellow"
-    return None

libs/cli/langgraph_cli/host_backend.py

@@ -70,7 +70,25 @@ class HostBackendClient:
                 f"Failed to decode response from {path}: {err}"
             ) from None
 
-    def create_deployment(self, payload: dict[str, Any]) -> dict[str, Any]:
+    def create_deployment(
+        self,
+        name: str,
+        deployment_type: str,
+        source: str,
+        config_path: str | None = None,
+        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": {},
+        }
+        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)
 
     def list_deployments(self, name_contains: str = "") -> dict[str, Any]:
@@ -92,6 +110,13 @@ class HostBackendClient:
             f"/v2/deployments/{deployment_id}/push-token",
         )
 
+    def request_upload_url(self, deployment_id: str) -> dict[str, Any]:
+        """Get a signed GCS URL for uploading the source tarball."""
+        return self._request(
+            "POST",
+            f"/v2/deployments/{deployment_id}/upload-url",
+        )
+
     def update_deployment(
         self,
         deployment_id: str,
@@ -99,6 +124,7 @@ class HostBackendClient:
         secrets: list[dict[str, str]] | None = None,
     ) -> dict[str, Any]:
         payload: dict[str, Any] = {
+            "revision_source": "internal_docker",
             "source_revision_config": {"image_uri": image_uri},
         }
         if secrets is not None:
@@ -109,6 +135,36 @@ class HostBackendClient:
             payload,
         )
 
+    def update_deployment_internal_source(
+        self,
+        deployment_id: str,
+        source_tarball_path: str,
+        config_path: str,
+        secrets: list[dict[str, str]] | None = None,
+        install_command: str | None = None,
+        build_command: str | None = None,
+    ) -> dict[str, Any]:
+        """Trigger a remote build revision with the uploaded tarball."""
+        payload: dict[str, Any] = {
+            "revision_source": "internal_source",
+            "source_revision_config": {
+                "source_tarball_path": source_tarball_path,
+                "langgraph_config_path": config_path,
+            },
+        }
+
+        source_config: dict[str, Any] = {}
+        if install_command is not None:
+            source_config["install_command"] = install_command
+        if build_command is not None:
+            source_config["build_command"] = build_command
+        if source_config:
+            payload["source_config"] = source_config
+
+        if secrets is not None:
+            payload["secrets"] = secrets
+        return self._request("PATCH", f"/v2/deployments/{deployment_id}", payload)
+
     def list_revisions(self, deployment_id: str, limit: int = 1) -> dict[str, Any]:
         return self._request(
             "GET",

libs/cli/langgraph_cli/progress.py

@@ -18,6 +18,9 @@ class Progress:
         self._show_elapsed = elapsed
         # use this to make sure we don't kill thread when we set msg to ""
         self._stop = threading.Event()
+        # signalled when the spinner has no text on screen
+        self._line_clear = threading.Event()
+        self._line_clear.set()
         self.spinner_generator = self.spinning_cursor()
 
     def spinner_iteration(self):
@@ -43,13 +46,16 @@ class Progress:
         start = time.monotonic()
         while not self._stop.is_set():
             if not self.message:
+                self._line_clear.set()
                 time.sleep(self.delay)
                 continue
             if self._show_elapsed:
                 self.message = self._format_elapsed(time.monotonic() - start)
             message = self.message
             if not message:
+                self._line_clear.set()
                 continue
+            self._line_clear.clear()
             sys.stdout.write(next(self.spinner_generator) + " " + message)
             sys.stdout.flush()
             time.sleep(self.delay)
@@ -60,6 +66,7 @@ class Progress:
                 + "\b" * (len(message) + 2)
             )
             sys.stdout.flush()
+            self._line_clear.set()
 
     def __enter__(self) -> Callable[[str], None]:
         if sys.stdout.isatty():
@@ -69,6 +76,8 @@ class Progress:
             def set_message(message):
                 self.message = message
                 self._base_message = message or self._base_message
+                if not message:
+                    self._line_clear.wait(timeout=0.5)
 
             return set_message
         else:

libs/cli/langgraph_cli/util.py

@@ -1,4 +1,4 @@
-from collections.abc import Sequence
+"""General-purpose utilities shared across the LangGraph CLI."""
 
 import click
 
@@ -25,67 +25,3 @@ def warn_non_wolfi_distro(config_json: dict) -> None:
             fg="yellow",
         )
         click.secho("")  # Empty line for better readability
-
-
-def _extract_deployment_url(deployment: dict[str, object]) -> str:
-    source_config = deployment.get("source_config")
-    if isinstance(source_config, dict):
-        custom_url = source_config.get("custom_url")
-        if isinstance(custom_url, str) and custom_url:
-            return custom_url
-    return "-"
-
-
-def format_deployments_table(deployments: Sequence[dict[str, object]]) -> str:
-    headers = ("Deployment ID", "Deployment Name", "Deployment URL")
-    rows = [
-        (
-            str(deployment.get("id", "-") or "-"),
-            str(deployment.get("name", "-") or "-"),
-            _extract_deployment_url(deployment),
-        )
-        for deployment in deployments
-    ]
-    widths = [
-        max(len(headers[index]), *(len(row[index]) for row in rows))
-        for index in range(len(headers))
-    ]
-
-    def format_row(row: Sequence[str]) -> str:
-        return "  ".join(value.ljust(widths[index]) for index, value in enumerate(row))
-
-    lines = [format_row(headers), format_row(tuple("-" * width for width in widths))]
-    lines.extend(format_row(row) for row in rows)
-    return "\n".join(lines)
-
-
-def format_revisions_table(revisions: Sequence[dict[str, object]]) -> str:
-    headers = ("Revision ID", "Status", "Created At")
-    latest_deployed_seen = False
-    rows = []
-    for revision in revisions:
-        status = str(revision.get("status", "-") or "-")
-        if status == "DEPLOYED":
-            if latest_deployed_seen:
-                status = "REPLACED"
-            else:
-                latest_deployed_seen = True
-        rows.append(
-            (
-                str(revision.get("id", "-") or "-"),
-                status,
-                str(revision.get("created_at", "-") or "-"),
-            )
-        )
-
-    widths = [
-        max(len(headers[index]), *(len(row[index]) for row in rows))
-        for index in range(len(headers))
-    ]
-
-    def format_row(row: Sequence[str]) -> str:
-        return "  ".join(value.ljust(widths[index]) for index, value in enumerate(row))
-
-    lines = [format_row(headers), format_row(tuple("-" * width for width in widths))]
-    lines.extend(format_row(row) for row in rows)
-    return "\n".join(lines)