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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: snowflake-sandbox-python
-Version: 0.2.2a4
+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.2a4 → 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.2a4 → 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.2a4"
+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]
@@ -142,19 +148,32 @@ ignore_missing_imports = true
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "function"
 testpaths = ["tests"]
-# Skip live tests by default — run with: pytest -m live --connection <name>
-addopts = "-m 'not live'"
+# Skip live and docs tests by default — run with:
+#   pytest -m live --connection <name>
+#   pytest -m docs            (add --docs-root if the checkout is not a sibling)
+addopts = "-m 'not live and not docs'"
 markers = [
     "live: tests that run against a real sandbox-api deployment",
+    # Needs a snowflake-prod-docs checkout, which is a SEPARATE repo. Excluded by
+    # default for the same reason `live` is: it reads state this repo does not own,
+    # so a plain `pytest` must never depend on it.
+    #
+    # Specifically, these tests pin the exact fenced-block sequence of every published
+    # tutorial. That is the right assertion for catching a broken tutorial, but it also
+    # means an ordinary tutorial edit in snowflake-prod-docs would fail THIS repo's
+    # suite for anyone who happens to keep a sibling docs checkout — a docs change
+    # breaking an SDK test run. CI never checks the docs repo out, so CI was never
+    # exposed; this keeps local runs equally unexposed.
+    #
+    # --docs-root still defaults to ../snowflake-prod-docs, so opting in needs no flag.
+    "docs: tests that read a snowflake-prod-docs checkout (see --docs-root)",
     # The promotion gate. A fast subset of `live` that a deployment must pass before it
     # is promoted to the next tier. Chosen so every member fails LOUDLY on an unhealthy
     # deployment: nothing that skips on error, and nothing unbounded. Run with `-m smoke`.
     #
-    # Measured on qa6, 2026-09-24: **15 tests, ~47s**. (The previous note here said
-    # "~10 creates, 3-5 min" — the count was right for its time but the duration was never
-    # close; don't budget against it.) Adding the two egress rows cost +16.6s over the
-    # 13-test predecessor's 29.9s. Worth re-measuring rather than trusting this line if the
-    # gate's cost ever becomes the question.
+    # Measured on qa6-mdrach, 2026-10-05: **30 tests, 83s** (15 sync + 15 async;
+    # the 2026-09-24 figure of 15 tests / ~47s was the sync client only). Adding
+    # the two egress rows cost +16.6s over the 13-test predecessor's 29.9s.
     #
     # This used to say "no egress tests (they assert 'BLOCKED' and so pass for the wrong
     # reason when networking is dead)". That reasoning was correct and is why egress was
@@ -192,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.2a4 → 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/_lifecycle_command.py

@@ -0,0 +1,108 @@
+"""``snow sandbox suspend`` and ``snow sandbox resume``.
+
+The CLI counterparts to ``Sandbox.suspend()`` / ``Sandbox.resume()``. Snowflake
+suspends an idle sandbox on its own timer; these let an operator bank a sandbox's
+state on demand, and wake one without running anything in it.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import typer
+
+# From _common, where these are DEFINED. Importing them via _get_command (which
+# re-exports them) is an implicit re-export and mypy rejects it.
+from snowflake.cli_sandbox._common import (
+    _CONN_HELP,
+    _USE_SNOW_CONN_HELP,
+    _apply_connection,
+    _resolve_sandbox_id,
+)
+
+
+def _suspend_command(
+    sandbox: str = typer.Argument(..., help="Sandbox name (or id) to suspend."),
+    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:
+    """Suspend a sandbox: snapshot its filesystem and tear the container down.
+
+    The sandbox keeps its files; the next thing that touches it brings it back on
+    that snapshot with a fresh process tree. Already-suspended is success.
+
+    Example:
+        snow sandbox suspend SANDBOX
+    """
+    from snowflake.cli_sandbox._adapter import sdk_connection
+    from snowflake.sandbox.exceptions import SandboxError
+    from snowflake.sandbox.sync_client import get_sandbox
+
+    _apply_connection(use_snow_connection, connection)
+    try:
+        # The SYNC client: AsyncSandbox.connect is itself a coroutine, so a bare
+        # asyncio.run(sb.suspend()) on its result would fail on a coroutine object.
+        # get_sandbox(), not Sandbox.connect(): _resolve_sandbox_id already turned a
+        # name into a cntr_ id, and connect() resolves its argument as a NAME -- so
+        # feeding it an id fails with "no sandbox named cntr_...".
+        #
+        # The SYNC client throughout: AsyncSandbox.connect is itself a coroutine, so a
+        # bare asyncio.run(sb.suspend()) on its result fails on a coroutine object.
+        get_sandbox(_resolve_sandbox_id(sandbox), connection=sdk_connection()).suspend()
+    except SandboxError as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(f"suspended {sandbox}")
+
+
+def _resume_command(
+    sandbox: str = typer.Argument(..., help="Sandbox name (or id) to resume."),
+    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:
+    """Wake a suspended sandbox without running anything in it.
+
+    Rarely needed -- anything that touches a sandbox resumes it anyway -- so this
+    is for paying the cold start up front. Returns once the resume is under way,
+    not once the sandbox is serving.
+
+    Example:
+        snow sandbox resume SANDBOX
+    """
+    from snowflake.cli_sandbox._adapter import sdk_connection
+    from snowflake.sandbox.exceptions import SandboxError
+    from snowflake.sandbox.sync_client import get_sandbox
+
+    _apply_connection(use_snow_connection, connection)
+    try:
+        # get_sandbox(), not Sandbox.connect(): _resolve_sandbox_id already turned a
+        # name into a cntr_ id, and connect() resolves its argument as a NAME.
+        get_sandbox(_resolve_sandbox_id(sandbox), connection=sdk_connection()).resume()
+    except SandboxError as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(f"resuming {sandbox}")
+
+
+_SUSPEND_HELP = "Suspend a sandbox, snapshotting its filesystem.\n\nExample:\n    snow sandbox suspend SANDBOX\n"
+_RESUME_HELP = "Resume a suspended sandbox.\n\nExample:\n    snow sandbox resume SANDBOX\n"