snowflake-sandbox-python 0.2.2a5__tar.gz → 0.2.2a6__tar.gz

{snowflake_sandbox_python-0.2.2a5 → snowflake_sandbox_python-0.2.2a6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: snowflake-sandbox-python
-Version: 0.2.2a5
+Version: 0.2.2a6
 Summary: Snowflake sandboxes — Python SDK and CLI.
 Author: Snowflake, Inc.
 License: 
@@ -222,11 +222,15 @@ License-File: LICENSE
 Requires-Dist: httpx[http2]<1.0,>=0.27
 Requires-Dist: typing-extensions>=4.6
 Requires-Dist: snowflake-connector-python>=3.6
+Requires-Dist: websockets<16,>=15
+Requires-Dist: protobuf<6,>=5.29
 Provides-Extra: cli
 Requires-Dist: snowflake-cli>=3.0; extra == "cli"
 Provides-Extra: connector
 Provides-Extra: dev
 Requires-Dist: pytest>=9; extra == "dev"
+Requires-Dist: grpcio-tools==1.71.0; extra == "dev"
+Requires-Dist: types-protobuf>=5.29; extra == "dev"
 Requires-Dist: pytest-timeout>=2.3; extra == "dev"
 Requires-Dist: pytest-asyncio>=1.4; extra == "dev"
 Requires-Dist: respx>=0.23; extra == "dev"
@@ -344,6 +348,46 @@ Auth via `SNOWFLAKE_ACCOUNT` + `SNOWFLAKE_TOKEN` env vars, a named connection in
 With none of those the SDK raises `"snowflake.sandbox has no endpoint to talk to: ..."`,
 which names every way to supply one.
 
+## HTTP and WebSocket endpoints
+
+Use `endpoint(port)` for ordinary HTTP or WebSocket applications. The SDK resolves
+an owned HTTPS origin and uses the current Snowflake credential for each request or
+handshake. Backend ingress converts the traffic into the shared Session gRPC protocol.
+
+```python
+from snowflake.sandbox import Sandbox
+
+sb = Sandbox.create(
+    image="/DB/SCHEMA/REPO/my-app:latest",
+    command=["python", "/app/server.py"],  # Your server listens on port 8080.
+    connection=connection,
+)
+with sb.endpoint(8080) as endpoint:
+    response = endpoint.request("GET", "/api/state")
+    response.raise_for_status()
+    print(response.json())
+    with endpoint.connect_websocket("/events") as socket:
+        socket.send("hello")
+        print(socket.recv())
+sb.disconnect()  # Preserve the running sandbox.
+```
+
+Resolving an endpoint does not start the guest application or wait for readiness.
+The first request or handshake reports availability; callers decide when to try again.
+
+`AsyncSandbox` exposes the same methods with `await` and `async with`. Use
+`endpoint.stream(method, path)` for incremental HTTP response reads; `request()` buffers
+the body. Both accept `headers`, `content` and `json`. Paths begin with `/` and remain
+within the endpoint's authority. Credential and Host headers are SDK-owned.
+Native HTTP and WebSocket clients omit browser Origin headers. Authentication
+still uses the current Snowflake credential and TLS verifies the owned authority.
+Origin remains reserved and cannot be supplied by callers.
+HTTP redirects are returned without being followed; WebSocket redirects are rejected.
+TLS verification defaults on, with request/handshake waits bounded by the connection
+configuration. Closing an endpoint closes its streams and sockets. Async cancellation
+also cancels pending operations. The application owns reconnect and protocol state;
+the transport makes one attempt and raises sanitized authentication or transport errors.
+
 ## CLI
 
 Installs as a [`snow sandbox`](https://github.com/snowflakedb/snowflake-cli) plugin:
@@ -375,3 +419,13 @@ uv run --extra docs mkdocs build --strict
 
 See `CONTRIBUTING.md` in the source repository for dev setup, how to add new
 methods, exceptions, and CLI commands.
+
+### Command execution
+
+`exec()` executes the program and its arguments directly. Ordinary commands such
+as `exec(["echo", "hello"])` do not require Python in the sandbox image. For shell
+builtins, use `exec(["sh", "-c", "cd /tmp && pwd"])`; for a script without a shebang,
+use `exec(["sh", "/path/script"])`. Arguments are literal, without shell expansion.
+`python -c` retains its historical alias to `python3 -c`.
+
+This requires a server with command-array support. Python jobs, sessions, and directory helpers still require Python in the image.

{snowflake_sandbox_python-0.2.2a5 → snowflake_sandbox_python-0.2.2a6}/README.md

@@ -104,6 +104,46 @@ Auth via `SNOWFLAKE_ACCOUNT` + `SNOWFLAKE_TOKEN` env vars, a named connection in
 With none of those the SDK raises `"snowflake.sandbox has no endpoint to talk to: ..."`,
 which names every way to supply one.
 
+## HTTP and WebSocket endpoints
+
+Use `endpoint(port)` for ordinary HTTP or WebSocket applications. The SDK resolves
+an owned HTTPS origin and uses the current Snowflake credential for each request or
+handshake. Backend ingress converts the traffic into the shared Session gRPC protocol.
+
+```python
+from snowflake.sandbox import Sandbox
+
+sb = Sandbox.create(
+    image="/DB/SCHEMA/REPO/my-app:latest",
+    command=["python", "/app/server.py"],  # Your server listens on port 8080.
+    connection=connection,
+)
+with sb.endpoint(8080) as endpoint:
+    response = endpoint.request("GET", "/api/state")
+    response.raise_for_status()
+    print(response.json())
+    with endpoint.connect_websocket("/events") as socket:
+        socket.send("hello")
+        print(socket.recv())
+sb.disconnect()  # Preserve the running sandbox.
+```
+
+Resolving an endpoint does not start the guest application or wait for readiness.
+The first request or handshake reports availability; callers decide when to try again.
+
+`AsyncSandbox` exposes the same methods with `await` and `async with`. Use
+`endpoint.stream(method, path)` for incremental HTTP response reads; `request()` buffers
+the body. Both accept `headers`, `content` and `json`. Paths begin with `/` and remain
+within the endpoint's authority. Credential and Host headers are SDK-owned.
+Native HTTP and WebSocket clients omit browser Origin headers. Authentication
+still uses the current Snowflake credential and TLS verifies the owned authority.
+Origin remains reserved and cannot be supplied by callers.
+HTTP redirects are returned without being followed; WebSocket redirects are rejected.
+TLS verification defaults on, with request/handshake waits bounded by the connection
+configuration. Closing an endpoint closes its streams and sockets. Async cancellation
+also cancels pending operations. The application owns reconnect and protocol state;
+the transport makes one attempt and raises sanitized authentication or transport errors.
+
 ## CLI
 
 Installs as a [`snow sandbox`](https://github.com/snowflakedb/snowflake-cli) plugin:
@@ -135,3 +175,13 @@ uv run --extra docs mkdocs build --strict
 
 See `CONTRIBUTING.md` in the source repository for dev setup, how to add new
 methods, exceptions, and CLI commands.
+
+### Command execution
+
+`exec()` executes the program and its arguments directly. Ordinary commands such
+as `exec(["echo", "hello"])` do not require Python in the sandbox image. For shell
+builtins, use `exec(["sh", "-c", "cd /tmp && pwd"])`; for a script without a shebang,
+use `exec(["sh", "/path/script"])`. Arguments are literal, without shell expansion.
+`python -c` retains its historical alias to `python3 -c`.
+
+This requires a server with command-array support. Python jobs, sessions, and directory helpers still require Python in the image.

{snowflake_sandbox_python-0.2.2a5 → snowflake_sandbox_python-0.2.2a6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "snowflake-sandbox-python"
-version = "0.2.2a5"
+version = "0.2.2a6"
 description = "Snowflake sandboxes — Python SDK and CLI."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -31,6 +31,8 @@ dependencies = [
     # reimplementing the file format, and imports it lazily so `import
     # snowflake.sandbox` stays fast. 3.6+ ships the tomlkit config_manager.
     "snowflake-connector-python>=3.6",
+    "websockets>=15,<16",
+    "protobuf>=5.29,<6",
 ]
 
 [project.optional-dependencies]
@@ -47,6 +49,8 @@ cli = [
 connector = []
 dev = [
     "pytest>=9",
+    "grpcio-tools==1.71.0",
+    "types-protobuf>=5.29",
     # No test timeout meant a hung shell()/create could sit indefinitely; a promotion
     # gate must always return a verdict.
     "pytest-timeout>=2.3",
@@ -82,10 +86,11 @@ namespaces = true
 
 [tool.setuptools.package-data]
 # PEP 561: ship the marker so downstream mypy/pyright pick up the SDK's types.
-"snowflake.sandbox" = ["py.typed"]
+"snowflake.sandbox" = ["py.typed", "_proto/*.pyi"]
 "snowflake.cli_sandbox" = ["py.typed"]
 
 [tool.ruff]
+extend-exclude = ["src/snowflake/sandbox/_proto"]
 line-length = 100
 target-version = "py311"
 src = ["src", "tests", "prototype"]
@@ -107,6 +112,7 @@ max-complexity = 15
 # Style/complexity sets govern src/; non-shipped code keeps correctness + format.
 [tool.ruff.lint.per-file-ignores]
 "tests/*" = ["B"]
+"src/snowflake/sandbox/_proto/*" = ["ALL"]
 "{tests,tools,examples,prototype}/**" = ["C901", "ASYNC", "SIM", "RUF"]
 
 [tool.ruff.lint.flake8-bugbear]
@@ -205,3 +211,8 @@ filterwarnings = [
 # -e '.[cli,dev]'`, used by CI) and uv (`uv sync --extra dev --extra docs`) share
 # a single source of truth. Install dev tooling with `--extra dev`/`--extra docs`
 # rather than `--group`.
+
+[[tool.mypy.overrides]]
+# protoc stubs use unparameterized Mapping; generated code is reviewed via drift tests.
+module = ["snowflake.sandbox._proto.*"]
+ignore_errors = true

{snowflake_sandbox_python-0.2.2a5 → snowflake_sandbox_python-0.2.2a6}/src/snowflake/cli_sandbox/_egress_flags.py

@@ -10,14 +10,10 @@ Spellings, chosen to match what the CLI already does elsewhere:
 * ``--eai NAME`` — repeatable, like ``--env``. Names an External Access Integration
   whose network rules the platform resolves; that is the only way to reach a host
   outside the built-in baseline.
-* ``--secret ENV_VAR=DB.SCHEMA.NAME@host[,host]`` — repeatable. The env var comes
+* ``--secret ENV_VAR=DB.SCHEMA.NAME[@host[,host]]`` — repeatable. The env var comes
   first because that is the order ``--env KEY=VAL`` established, and it is the half
-  you read inside the sandbox. Omitting ``ENV_VAR=`` takes the SDK's derived
-  ``CNG_SECRET_<FQN>`` name. The ``@host`` scopes where the credential may be sent and
-  is **always required**: the SDK refuses an unscoped credential rather than let it
-  egress anywhere. (Its error text says ``host=`` becomes optional once an EAI supplies
-  the hosts — that is not implemented; an EAI does not relax the requirement, verified
-  against `compile_egress`.)
+  you read inside the sandbox. The ``@host`` scopes where the credential may be sent
+  and is required unless an ``--eai`` supplies the host grant.
 * ``--no-default-egress`` — the closed level: Snowflake and its stages only, no
   baseline package-manager hosts. An ``--eai`` still grants on top of it, which is
   why this is not called ``--no-egress``.
@@ -27,7 +23,7 @@ from __future__ import annotations
 
 import typer
 
-from snowflake.sandbox.egress import Egress, compile_egress
+from snowflake.sandbox.egress import Egress, compile_egress, compile_secrets
 from snowflake.sandbox.secret import Secret
 
 __all__ = ["EAI_HELP", "NO_DEFAULT_EGRESS_HELP", "SECRET_HELP", "build_egress"]
@@ -38,10 +34,17 @@ EAI_HELP = (
     "readable or the platform refuses the create."
 )
 
+OUTBOUND_WIF_HOST_HELP = (
+    "Host that gets a Snowflake workload identity token as Authorization: Bearer, so it "
+    "can verify the calling account without a stored secret; repeatable. An exact host "
+    "or a leading-dot suffix (.example.com). It does not open egress: the host must also "
+    "be reachable, e.g. through --eai."
+)
+
 SECRET_HELP = (
-    "Snowflake SECRET to inject, as ENV_VAR=DB.SCHEMA.NAME@host[,host]; repeatable. "
-    "The @host scopes where the credential may be sent and is required. Omit ENV_VAR= "
-    "for the derived CNG_SECRET_<FQN> name."
+    "Snowflake SECRET to inject, as ENV_VAR=DB.SCHEMA.NAME[@host[,host]]; repeatable. "
+    "The @host scopes where the credential may be sent and is required unless an "
+    "--eai supplies the host grant. ENV_VAR= is required."
 )
 
 NO_DEFAULT_EGRESS_HELP = (
@@ -64,6 +67,8 @@ def _parse_secret(raw: str) -> Secret:
         env_var, spec = env_var.strip(), spec.strip()
         if not env_var:
             raise typer.BadParameter(f"empty env var in {raw!r} (expected ENV_VAR=DB.SCHEMA.NAME)")
+    else:
+        raise typer.BadParameter(f"{raw!r}: expected ENV_VAR=DB.SCHEMA.NAME[@host]")
 
     hosts: tuple[str, ...] = ()
     if "@" in spec:
@@ -89,38 +94,42 @@ def build_egress(
     eai: list[str] | None,
     secret: list[str] | None,
     no_default_egress: bool,
+    outbound_wif_host: list[str] | None = None,
 ) -> tuple[Egress | None, tuple[Secret, ...]]:
     """`(egress, secrets)` for these flags — both empty when none were given.
 
     Two values because that is the shape `Sandbox.create()` takes: secrets are authored
-    alongside egress but are their own argument (they nest under egress only on the
-    wire, where `compile_egress` puts them).
+    alongside egress and sent as their own top-level create field.
 
     `None` rather than an empty `Egress` when nothing was passed, so the create body
     stays byte-identical to today's for every existing caller.
     """
     integrations = tuple(dict.fromkeys(name.strip() for name in (eai or []) if name.strip()))
     secrets = tuple(_parse_secret(raw) for raw in (secret or []))
-    if not integrations and not secrets and not no_default_egress:
+    wif_hosts = tuple(dict.fromkeys(h.strip() for h in (outbound_wif_host or []) if h.strip()))
+    if not integrations and not secrets and not no_default_egress and not wif_hosts:
         return None, ()
 
-    egress = Egress(
-        external_access_integrations=integrations,
-        # Uses the current parameter name. The CLI FLAG stays `--no-default-egress`: it is
-        # released, renaming it would break users' scripts, and that is a separate decision
-        # from the library parameter's name. So the flag spelling and the parameter spelling
-        # differ here deliberately — the alternative is the CLI depending on a deprecated
-        # parameter, which is worse.
-        **({"allow_public_package_registries": False} if no_default_egress else {}),
-    )
     # Validate now, not at create time. `compile_egress` is pure and is what the client
     # runs anyway -- but it runs *after* connecting, so a mistyped host pair otherwise
     # costs a Snowflake round trip before saying so. These are usage errors; they should
-    # cost nothing.
+    # cost nothing. Egress() is inside the try too: it rejects a bad --outbound-wif-host.
     from snowflake.sandbox.exceptions import SandboxError
 
     try:
-        compile_egress(egress, secrets)
+        egress = Egress(
+            external_access_integrations=integrations,
+            # Uses the current parameter name. The CLI FLAG stays `--no-default-egress`: it
+            # is released, renaming it would break users' scripts, and that is a separate
+            # decision from the library parameter's name. So the flag spelling and the
+            # parameter spelling differ here deliberately — the alternative is the CLI
+            # depending on a deprecated parameter, which is worse. None is unset, which
+            # sends nothing for the level.
+            allow_public_package_registries=False if no_default_egress else None,
+            outbound_wif_hosts=wif_hosts,
+        )
+        compile_egress(egress, ())
+        compile_secrets(secrets, has_eai=bool(integrations))
     except SandboxError as exc:
         raise typer.BadParameter(str(exc)) from exc
     return egress, secrets

snowflake_sandbox_python-0.2.2a6/src/snowflake/cli_sandbox/_git_repo_flags.py

@@ -0,0 +1,58 @@
+"""`--git-repo` / `--git-integration`: mount Git repositories into a run's sandbox.
+
+* ``--git-repo URL[=MOUNT_PATH]`` — repeatable. The first ``=`` starts the mount path.
+* ``--git-integration NAME`` — the ``EXTERNAL_APPLICATION`` integration every
+  ``--git-repo`` is cloned through, one per run.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import typer
+
+if TYPE_CHECKING:
+    from snowflake.sandbox.git_repo import GitRepo
+
+__all__ = ["GIT_INTEGRATION_HELP", "GIT_REPO_HELP", "build_git_repos"]
+
+GIT_REPO_HELP = (
+    "Git repository to mount, as an https URL with an optional =MOUNT_PATH "
+    "(default /mnt/repos/<repo>); repeatable. Needs --git-integration. The default "
+    "branch is mounted writable, and git push from the sandbox has no credential."
+)
+
+GIT_INTEGRATION_HELP = (
+    "Snowflake EXTERNAL_APPLICATION integration that every --git-repo is cloned "
+    "through, with your own authorization of it."
+)
+
+
+def build_git_repos(raw: list[str] | None, integration: str | None) -> tuple[GitRepo, ...]:
+    """The `GitRepo`s for these flags, or a `typer.BadParameter`."""
+    from snowflake.sandbox.exceptions import SandboxError
+    from snowflake.sandbox.git_repo import GitRepo, validate_git_repos
+
+    if not raw:
+        if integration:
+            raise typer.BadParameter("--git-integration needs at least one --git-repo.")
+        return ()
+    if not integration:
+        raise typer.BadParameter(
+            "--git-repo needs --git-integration NAME, the EXTERNAL_APPLICATION "
+            "integration the repository is cloned through."
+        )
+    repos: list[GitRepo] = []
+    for spec in raw:
+        url, _, mount_path = spec.strip().partition("=")
+        try:
+            repos.append(
+                GitRepo(url.strip(), integration=integration, mount_path=mount_path.strip())
+            )
+        except SandboxError as exc:
+            raise typer.BadParameter(f"--git-repo {spec!r}: {exc}") from exc
+    try:
+        validate_git_repos(repos)
+    except SandboxError as exc:
+        raise typer.BadParameter(f"--git-repo: {exc}") from exc
+    return tuple(repos)

snowflake_sandbox_python-0.2.2a6/src/snowflake/cli_sandbox/_remote_command.py

@@ -0,0 +1,168 @@
+"""CLI entry points for SSH, local TCP forwarding and the desktop page."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from contextlib import redirect_stdout
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import typer
+
+from snowflake.cli_sandbox._common import (
+    _CONN_HELP,
+    _USE_SNOW_CONN_HELP,
+    _apply_connection,
+    _resolve_sandbox_id,
+)
+from snowflake.sandbox.exceptions import SandboxError
+
+if TYPE_CHECKING:
+    from snowflake.sandbox.config import Config
+
+_SSH_HELP = "Connect with OpenSSH over an authenticated sandbox tunnel. Requires OpenSSH on PATH.\n\nExample:\n    snow sandbox ssh my-sandbox\n    snow sandbox ssh my-sandbox --cmd 'uname -a'"
+_PORT_FORWARD_HELP = "Forward a loopback TCP port to a port inside an existing sandbox.\n\nExample:\n    snow sandbox port-forward my-sandbox 8080 --local-port 18080"
+_DESKTOP_HELP = "Open the remote desktop page for an existing sandbox.\n\nExample:\n    snow sandbox desktop my-sandbox\n    snow sandbox desktop my-sandbox --no-open"
+
+
+def _remote_config(use_snow_connection: bool, connection: str | None) -> Config:
+    from snowflake.cli_sandbox._adapter import sdk_connection
+    from snowflake.sandbox.config import resolve_config
+
+    _apply_connection(use_snow_connection, connection=connection)
+    return resolve_config(connection=sdk_connection())
+
+
+def _ssh_command(
+    sandbox_id: str = typer.Argument(..., help="Existing sandbox name or app id."),
+    user: str = typer.Option("root", "--user", help="SSH login user inside the sandbox."),
+    cmd: str | None = typer.Option(
+        None, "--cmd", help="Remote command; omit for an interactive SSH session."
+    ),
+    use_snow_connection: bool = typer.Option(
+        True, "--use-snow-connection/--no-snow-connection", help=_USE_SNOW_CONN_HELP
+    ),
+    connection: str | None = typer.Option(None, "--connection", "-c", help=_CONN_HELP),
+    proxy: bool = typer.Option(False, "--proxy", hidden=True),
+    identity: Path | None = typer.Option(None, "--identity", hidden=True),
+    known_hosts: Path | None = typer.Option(None, "--known-hosts", hidden=True),
+    **options: Any,
+) -> None:
+    from snowflake.sandbox._preview import preview_url
+    from snowflake.sandbox._ssh import run_ssh, ssh_proxy
+    from snowflake.sandbox._tunnel import resolve_remote_url
+
+    try:
+        if sandbox_id.startswith("cntr_"):
+            preview_url(sandbox_id, 8079, "org-account.example")
+        if proxy and (identity is None or known_hosts is None):
+            raise typer.BadParameter("--proxy requires --identity and --known-hosts")
+        if proxy or not sandbox_id.startswith("cntr_"):
+            # Connector/browser-login notices must not enter the SSH stream.
+            with redirect_stdout(sys.stderr):
+                config = _remote_config(use_snow_connection, connection)
+                sandbox_id = _resolve_sandbox_id(sandbox_id)
+        # Validate before key generation or spawning a process.
+        preview_url(sandbox_id, 8079, "org-account.example")
+        if proxy:
+            if identity is None or known_hosts is None:
+                raise typer.BadParameter("--proxy requires --identity and --known-hosts")
+
+            async def pump() -> None:
+                with redirect_stdout(sys.stderr):
+                    url = await resolve_remote_url(sandbox_id, config, service="ssh")
+                await ssh_proxy(
+                    url, config, identity=identity, known_hosts=known_hosts, alias=sandbox_id
+                )
+
+            asyncio.run(pump())
+            code = 0
+        else:
+            code = run_ssh(
+                sandbox_id,
+                user=user,
+                command=cmd,
+                connection=connection,
+                use_snow_connection=use_snow_connection,
+            )
+    except KeyboardInterrupt:
+        raise typer.Exit(130) from None
+    except (SandboxError, OSError) as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(1) from exc
+    raise typer.Exit(code)
+
+
+def _port_forward_command(
+    sandbox_id: str = typer.Argument(..., help="Existing sandbox name or app id."),
+    port: int = typer.Argument(..., help="TCP port inside the sandbox."),
+    local_port: int | None = typer.Option(
+        None, "--local-port", help="Loopback port to listen on (default: remote port)."
+    ),
+    use_snow_connection: bool = typer.Option(
+        True, "--use-snow-connection/--no-snow-connection", help=_USE_SNOW_CONN_HELP
+    ),
+    connection: str | None = typer.Option(None, "--connection", "-c", help=_CONN_HELP),
+    **options: Any,
+) -> None:
+    from snowflake.sandbox._preview import validate_preview_port
+    from snowflake.sandbox._tunnel import forward_port, remote_url, resolve_remote_url
+
+    try:
+        remote_url(
+            sandbox_id if sandbox_id.startswith("cntr_") else "cntr_validation",
+            "org-account.example",
+            port=port,
+        )
+        listen_port = validate_preview_port(port if local_port is None else local_port)
+        config = _remote_config(use_snow_connection, connection)
+        sandbox_id = _resolve_sandbox_id(sandbox_id)
+
+        async def forward() -> None:
+            url = await resolve_remote_url(sandbox_id, config, port=port)
+            await forward_port(
+                url,
+                config,
+                port=port,
+                local_port=listen_port,
+                ready=lambda bound: typer.echo(
+                    f"Forwarding 127.0.0.1:{bound} to {sandbox_id}:{port}", err=True
+                ),
+            )
+
+        asyncio.run(forward())
+    except KeyboardInterrupt:
+        raise typer.Exit(130) from None
+    except (SandboxError, OSError) as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(1) from exc
+
+
+def _desktop_command(
+    sandbox_id: str = typer.Argument(..., help="Existing sandbox name or app id."),
+    no_open: bool = typer.Option(
+        False, "--no-open", help="Print the desktop URL without opening a browser."
+    ),
+    use_snow_connection: bool = typer.Option(
+        True, "--use-snow-connection/--no-snow-connection", help=_USE_SNOW_CONN_HELP
+    ),
+    connection: str | None = typer.Option(None, "--connection", "-c", help=_CONN_HELP),
+    **options: Any,
+) -> None:
+    import webbrowser
+
+    from snowflake.sandbox._tunnel import remote_url, resolve_remote_url
+
+    try:
+        if sandbox_id.startswith("cntr_"):
+            remote_url(sandbox_id, "org-account.example", service="desktop")
+        config = _remote_config(use_snow_connection, connection)
+        sandbox_id = _resolve_sandbox_id(sandbox_id)
+        url = asyncio.run(resolve_remote_url(sandbox_id, config, service="desktop"))
+        typer.echo(url)
+        if not no_open:
+            webbrowser.open(url)
+    except (SandboxError, OSError) as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(1) from exc