opensandbox-cli 1.1.2.dev2026102001__tar.gz → 1.2.1__tar.gz

{opensandbox_cli-1.1.2.dev2026102001 → opensandbox_cli-1.2.1}/.gitignore

@@ -294,3 +294,7 @@ obj/
 # fast-sandbox pinned source checkout (materialized by
 # manifests/release/build-fast-sandbox.sh from manifests/third-party/fast-sandbox.commit)
 .fast-sandbox/
+
+# Test-only localhost certificate pair for the egress OSEP-0025 resolver stub
+# (fixtures/README.md documents regeneration; these certify nothing).
+!components/egress/tests/resolver/fixtures/*.pem

{opensandbox_cli-1.1.2.dev2026102001 → opensandbox_cli-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: opensandbox-cli
-Version: 1.1.2.dev2026102001
+Version: 1.2.1
 Summary: OpenSandbox CLI - Command-line interface for managing sandboxes
 Project-URL: Homepage, https://open-sandbox.ai
 Project-URL: Repository, https://github.com/opensandbox-group/OpenSandbox
@@ -224,11 +224,12 @@ Classifier: Topic :: Software Development :: Libraries
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: click<9.0,>=8.1.0
-Requires-Dist: opensandbox==1.1.2.dev20261020
+Requires-Dist: opensandbox<2.0.0,>=1.2.1
 Requires-Dist: pyyaml<7.0,>=6.0
 Requires-Dist: rich<14.0,>=13.0.0
 Requires-Dist: tomli>=2.0.0; python_version < '3.11'
 Requires-Dist: tomlkit<1.0,>=0.13.0
+Requires-Dist: websockets>=14.0
 Description-Content-Type: text/markdown
 
 # OpenSandbox CLI
@@ -435,7 +436,8 @@ osb sandbox create -f sandbox-request.json -o json
 Templates are golden-image builds; the build runs asynchronously, so poll `template get` until the status phase is `Succeeded`. Template management requires a Kubernetes-backed runtime.
 
 ```bash
-osb template create --image python:3.12 --publish s3://bucket/publish -o json
+osb template create --image python:3.12 --publish s3://bucket/publish --format native -o json
+osb template create --image python:3.12 --publish oci://registry.example.com/sandbox/templates --format overlaybd -o json
 osb template get <template-id> -o json
 osb template list -o json
 osb template delete <template-id> -o json
@@ -451,11 +453,14 @@ osb template create -f template-request.json -o json
 {
   "image": "python:3.12",
   "publish": "s3://bucket/publish",
+  "format": "native",
   "resourceLimits": { "cpu": "1", "memory": "512Mi" },
   "readiness": { "probe": "tcp://127.0.0.1:44772", "warmupSeconds": 60 }
 }
 ```
 
+OCI targets must name a repository without a tag or digest. Use `overlaybd` (the default) for OCI and explicitly select `native` for S3. The builder returns an immutable OCI reference in `status.manifestRef`; `sandbox create --template` uses that reference automatically. See [OCI template setup](../docs/guides/oci-templates.md) for Registry Secrets and runtime prerequisites.
+
 ### Manage snapshots
 
 Snapshots capture a sandbox's state and can back new sandboxes.
@@ -511,7 +516,7 @@ osb command logs <sandbox-id> <execution-id> -o json
 
 Background start errors or a stream ending before startup confirmation make the CLI exit non-zero without success metadata. After a successful start, use `command status` and `command logs` to check the process's eventual result.
 
-By default the payload after `--` is joined into one shell command string, so pipelines, redirection, and `$VAR` expansion work as in a terminal. Add `--argv` to pass the arguments to the executable as a literal argv list (no shell) when values such as `$HOME`, quotes, embedded spaces, or empty strings must reach the process unchanged. `--argv` needs a sandbox image whose execd accepts argv requests:
+By default each payload word after `--` is quoted as a single shell token and the tokens are joined into one shell command line that the sandbox's shell runs. Shell syntax such as pipelines or redirection must therefore ride inside an explicit word (`-- sh -c 'echo hi > /tmp/x'`); an unquoted `$VAR` is expanded by your own terminal before the CLI sees it, while a quoted one reaches the sandbox shell literally. Add `--argv` to pass the arguments to the executable as a literal argv list (no shell) when values such as `$HOME`, quotes, embedded spaces, or empty strings must reach the process unchanged. `--argv` needs a sandbox image whose execd accepts argv requests:
 
 ```bash
 osb command run <sandbox-id> -o raw --argv -- python3 -c "import sys; print(sys.argv[1:])" "a b" '$HOME' "x'y" ""
@@ -527,6 +532,17 @@ osb command session run <sandbox-id> <session-id> -o raw -- sh -c 'echo $FOO'
 osb command session delete <sandbox-id> <session-id> -o json
 ```
 
+### Open an interactive terminal
+
+`osb terminal` attaches your current terminal to a real PTY inside the sandbox (colors, `stty`, and resize all behave like a local shell). Exit the remote shell (or press Ctrl-D) to leave; the remote exit code becomes the command's exit code.
+
+```bash
+osb terminal <sandbox-id>
+osb terminal <sandbox-id> -w /workspace
+```
+
+Requires an interactive TTY, and is supported on Unix, macOS, and Linux. If the connection drops while the shell is still running, the session is kept server-side and its id is printed so it can be inspected or removed via the execd API; a clean exit tears the session down.
+
 ### Work with files
 
 ```bash
@@ -635,6 +651,7 @@ The main command groups are:
 - `osb template`: golden-image template builds
 - `osb snapshot`: snapshot management
 - `osb command`: command execution and persistent sessions
+- `osb terminal`: interactive PTY terminal into a sandbox
 - `osb file`: file and directory operations
 - `osb egress`: runtime egress policy
 - `osb diagnostics`: stable diagnostics logs and events
@@ -721,7 +738,8 @@ api_key = "your-api-key"
 domain = "localhost:8080"
 protocol = "http"
 request_timeout = 30
-use_server_proxy = false
+# use_server_proxy is deprecated (maintenance mode); prefer the ingress gateway for data-plane traffic.
+# use_server_proxy = false
 
 [output]
 color = true

{opensandbox_cli-1.1.2.dev2026102001 → opensandbox_cli-1.2.1}/README.md

@@ -202,7 +202,8 @@ osb sandbox create -f sandbox-request.json -o json
 Templates are golden-image builds; the build runs asynchronously, so poll `template get` until the status phase is `Succeeded`. Template management requires a Kubernetes-backed runtime.
 
 ```bash
-osb template create --image python:3.12 --publish s3://bucket/publish -o json
+osb template create --image python:3.12 --publish s3://bucket/publish --format native -o json
+osb template create --image python:3.12 --publish oci://registry.example.com/sandbox/templates --format overlaybd -o json
 osb template get <template-id> -o json
 osb template list -o json
 osb template delete <template-id> -o json
@@ -218,11 +219,14 @@ osb template create -f template-request.json -o json
 {
   "image": "python:3.12",
   "publish": "s3://bucket/publish",
+  "format": "native",
   "resourceLimits": { "cpu": "1", "memory": "512Mi" },
   "readiness": { "probe": "tcp://127.0.0.1:44772", "warmupSeconds": 60 }
 }
 ```
 
+OCI targets must name a repository without a tag or digest. Use `overlaybd` (the default) for OCI and explicitly select `native` for S3. The builder returns an immutable OCI reference in `status.manifestRef`; `sandbox create --template` uses that reference automatically. See [OCI template setup](../docs/guides/oci-templates.md) for Registry Secrets and runtime prerequisites.
+
 ### Manage snapshots
 
 Snapshots capture a sandbox's state and can back new sandboxes.
@@ -278,7 +282,7 @@ osb command logs <sandbox-id> <execution-id> -o json
 
 Background start errors or a stream ending before startup confirmation make the CLI exit non-zero without success metadata. After a successful start, use `command status` and `command logs` to check the process's eventual result.
 
-By default the payload after `--` is joined into one shell command string, so pipelines, redirection, and `$VAR` expansion work as in a terminal. Add `--argv` to pass the arguments to the executable as a literal argv list (no shell) when values such as `$HOME`, quotes, embedded spaces, or empty strings must reach the process unchanged. `--argv` needs a sandbox image whose execd accepts argv requests:
+By default each payload word after `--` is quoted as a single shell token and the tokens are joined into one shell command line that the sandbox's shell runs. Shell syntax such as pipelines or redirection must therefore ride inside an explicit word (`-- sh -c 'echo hi > /tmp/x'`); an unquoted `$VAR` is expanded by your own terminal before the CLI sees it, while a quoted one reaches the sandbox shell literally. Add `--argv` to pass the arguments to the executable as a literal argv list (no shell) when values such as `$HOME`, quotes, embedded spaces, or empty strings must reach the process unchanged. `--argv` needs a sandbox image whose execd accepts argv requests:
 
 ```bash
 osb command run <sandbox-id> -o raw --argv -- python3 -c "import sys; print(sys.argv[1:])" "a b" '$HOME' "x'y" ""
@@ -294,6 +298,17 @@ osb command session run <sandbox-id> <session-id> -o raw -- sh -c 'echo $FOO'
 osb command session delete <sandbox-id> <session-id> -o json
 ```
 
+### Open an interactive terminal
+
+`osb terminal` attaches your current terminal to a real PTY inside the sandbox (colors, `stty`, and resize all behave like a local shell). Exit the remote shell (or press Ctrl-D) to leave; the remote exit code becomes the command's exit code.
+
+```bash
+osb terminal <sandbox-id>
+osb terminal <sandbox-id> -w /workspace
+```
+
+Requires an interactive TTY, and is supported on Unix, macOS, and Linux. If the connection drops while the shell is still running, the session is kept server-side and its id is printed so it can be inspected or removed via the execd API; a clean exit tears the session down.
+
 ### Work with files
 
 ```bash
@@ -402,6 +417,7 @@ The main command groups are:
 - `osb template`: golden-image template builds
 - `osb snapshot`: snapshot management
 - `osb command`: command execution and persistent sessions
+- `osb terminal`: interactive PTY terminal into a sandbox
 - `osb file`: file and directory operations
 - `osb egress`: runtime egress policy
 - `osb diagnostics`: stable diagnostics logs and events
@@ -488,7 +504,8 @@ api_key = "your-api-key"
 domain = "localhost:8080"
 protocol = "http"
 request_timeout = 30
-use_server_proxy = false
+# use_server_proxy is deprecated (maintenance mode); prefer the ingress gateway for data-plane traffic.
+# use_server_proxy = false
 
 [output]
 color = true

{opensandbox_cli-1.1.2.dev2026102001 → opensandbox_cli-1.2.1}/pyproject.toml

@@ -42,13 +42,17 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    # Keep this test CLI on the matching published SDK development build.
-    "opensandbox==1.1.2.dev20261020",
+    # `command run --argv` passes a list to commands.run; the SDK accepts a
+    # list there from 0.1.17. Release the CLI only after that SDK is published.
+    "opensandbox>=1.2.1,<2.0.0",
     "click>=8.1.0,<9.0",
     "rich>=13.0.0,<14.0",
     "pyyaml>=6.0,<7.0",
     "tomlkit>=0.13.0,<1.0",
     "tomli>=2.0.0; python_version < '3.11'",
+    # `osb terminal` drives the execd PTY WebSocket; 14+ renamed extra_headers
+    # to additional_headers, which the terminal client uses.
+    "websockets>=14.0",
 ]
 
 [project.urls]

{opensandbox_cli-1.1.2.dev2026102001 → opensandbox_cli-1.2.1}/src/opensandbox_cli/commands/command.py

@@ -147,9 +147,12 @@ def _handle_execution_error(
     help="Run a command in a sandbox. Use `--` before the sandbox command payload.",
     epilog=(
         "Separator rule: use `--` before the sandbox command payload.\n\n"
-        "By default the payload is joined into one shell command string. Add "
-        "`--argv` to pass the arguments to the executable as-is (no shell), so "
-        "literal `$HOME`, quotes, and empty strings are preserved; this needs a "
+        "By default each payload word is quoted as a single shell token and "
+        "the tokens are joined into one shell command line, so shell syntax "
+        "such as redirects or pipes must ride inside an explicit word "
+        "(for example: -- sh -c 'echo hi > /tmp/x'). Add `--argv` to pass "
+        "the arguments to the executable as-is (no shell), so literal "
+        "`$HOME`, quotes, and empty strings are preserved; this needs a "
         "sandbox image whose execd accepts argv requests."
     ),
 )

{opensandbox_cli-1.1.2.dev2026102001 → opensandbox_cli-1.2.1}/src/opensandbox_cli/commands/config_cmd.py

@@ -26,7 +26,7 @@ from tomlkit.exceptions import ParseError
 from tomlkit.items import InlineTable, Table
 
 from opensandbox_cli.client import ClientContext
-from opensandbox_cli.config import init_config_file, resolve_config
+from opensandbox_cli.config import STRING_KEYS, init_config_file, resolve_config
 from opensandbox_cli.utils import handle_errors, output_option, prepare_output
 
 
@@ -53,7 +53,8 @@ def config_init(obj: ClientContext, force: bool, output_format: str | None) -> N
         path = init_config_file(obj.config_path, force=force)
         output.success(f"Config file created: {path}")
     except FileExistsError as exc:
-        output.warning(str(exc))
+        output.error(str(exc))
+        raise click.exceptions.Exit(1) from None
 
 
 _SENSITIVE_CONFIG_KEYS = {
@@ -166,7 +167,7 @@ def config_set(
     if not isinstance(table, (Table, InlineTable, OutOfOrderTableProxy)):
         raise click.ClickException(f"Cannot set {key}: '{section}' is not a TOML table.")
 
-    table[field] = _parse_toml_value(value)
+    table[field] = value if key in STRING_KEYS else _parse_toml_value(value)
     path.write_text(tomlkit.dumps(document), encoding="utf-8")
 
     obj.output.success(f"Set {key} = {value}")

{opensandbox_cli-1.1.2.dev2026102001 → opensandbox_cli-1.2.1}/src/opensandbox_cli/commands/egress.py

@@ -26,7 +26,7 @@ from opensandbox_cli.utils import handle_errors, output_option, prepare_output
 def _parse_rule(value: str) -> NetworkRule:
     """Parse ACTION=TARGET into a NetworkRule."""
     action, sep, target = value.partition("=")
-    if not sep:
+    if not sep or not target.strip():
         raise click.BadParameter(
             f"Invalid rule '{value}'. Use ACTION=TARGET, for example allow=pypi.org."
         )

{opensandbox_cli-1.1.2.dev2026102001 → opensandbox_cli-1.2.1}/src/opensandbox_cli/commands/sandbox.py

@@ -1015,12 +1015,20 @@ def _parse_metric_stream_line(line: str) -> tuple[SandboxMetrics | None, str | N
     if not payload:
         return None, None
 
-    decoded: Any = json.loads(payload)
+    try:
+        decoded: Any = json.loads(payload)
+    except json.JSONDecodeError:
+        return None, "Metrics stream error: invalid JSON"
+
     if isinstance(decoded, dict) and decoded.get("error"):
         return None, f"Metrics stream error: {decoded['error']}"
-    if isinstance(decoded, dict) and "cpu_used_pct" in decoded:
-        return MetricsModelConverter.to_sandbox_metrics(Metrics.from_dict(decoded)), None
-    return SandboxMetrics.model_validate(decoded), None
+
+    try:
+        if isinstance(decoded, dict) and "cpu_used_pct" in decoded:
+            return MetricsModelConverter.to_sandbox_metrics(Metrics.from_dict(decoded)), None
+        return SandboxMetrics.model_validate(decoded), None
+    except (KeyError, TypeError, ValueError, ValidationError) as exc:
+        return None, f"Metrics stream error: {exc}"
 
 
 def _describe_create_timeout(

{opensandbox_cli-1.1.2.dev2026102001 → opensandbox_cli-1.2.1}/src/opensandbox_cli/commands/template.py

@@ -55,7 +55,7 @@ def template_group(ctx: click.Context) -> None:
     "--publish",
     "-p",
     default=None,
-    help="S3-compatible publish target for the built artifacts (e.g. s3://bucket/publish). Required unless --file is used.",
+    help="Publish target: s3://bucket/publish (native) or oci://registry/repository (overlaybd, no tag or digest). Required unless --file is used.",
 )
 @click.option(
     "--file",
@@ -233,6 +233,9 @@ def template_get(obj, template_id: str, output_format: str | None) -> None:
     status_val = d.get("status")
     if isinstance(status_val, dict):
         d["status"] = status_val.get("phase", str(status_val))
+        # model_dump uses the field name; accept the wire alias too.
+        manifest_ref = status_val.get("manifest_ref", status_val.get("manifestRef"))
+        d["manifest_ref"] = manifest_ref
         if status_val.get("message"):
             d["status_message"] = status_val["message"]
     readiness_val = d.get("readiness")

opensandbox_cli-1.2.1/src/opensandbox_cli/commands/terminal.py

@@ -0,0 +1,415 @@
+# Copyright 2026 The OpenSandbox Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Interactive terminal into a sandbox over the execd PTY WebSocket.
+
+Frame protocol is defined in components/execd/PTY.md.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import signal
+import sys
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterator
+from contextlib import contextmanager
+from datetime import timedelta
+from typing import IO, Protocol
+
+import click
+import httpx
+import websockets
+from opensandbox.constants import DEFAULT_EXECD_PORT
+
+from opensandbox_cli.client import ClientContext
+from opensandbox_cli.utils import handle_errors
+
+# Binary WebSocket frame type bytes, mirroring execd pkg/web/model.
+BIN_STDIN = 0x00
+BIN_STDOUT = 0x01
+BIN_STDERR = 0x02
+BIN_REPLAY = 0x03
+
+ReadFn = Callable[[], Awaitable[bytes]]
+WriteFn = Callable[[bytes], None]
+SizeFn = Callable[[], tuple[int, int]]
+
+
+class WSDuplex(Protocol):
+    """Minimal WebSocket surface used by the relay loop."""
+
+    def send(self, message: bytes | str) -> Awaitable[None]: ...
+
+    def __aiter__(self) -> AsyncIterator[bytes | str]: ...
+
+
+def _ws_scheme(protocol: str) -> str:
+    return "wss" if protocol == "https" else "ws"
+
+
+def _execd_base(endpoint: str) -> str:
+    """Normalize an execd endpoint (``host:port`` or ``host/proxy/path``)."""
+    return endpoint.rstrip("/")
+
+
+def _create_pty_session(
+    base_url: str,
+    headers: dict[str, str],
+    *,
+    workdir: str | None,
+    timeout: timedelta,
+) -> str:
+    body: dict[str, str] = {}
+    if workdir:
+        body["cwd"] = workdir
+    try:
+        response = httpx.post(
+            f"{base_url}/pty",
+            headers=headers,
+            json=body,
+            timeout=timeout.total_seconds(),
+        )
+    except httpx.HTTPError as exc:
+        raise click.ClickException(f"Could not reach the sandbox execd: {exc}") from exc
+    if response.status_code != 201:
+        detail = response.text.strip() or response.reason_phrase
+        raise click.ClickException(
+            f"Creating a PTY session failed with HTTP {response.status_code}: {detail}"
+        )
+    session_id = response.json().get("session_id")
+    if not session_id:
+        raise click.ClickException("The execd response did not include a session_id.")
+    return str(session_id)
+
+
+def _delete_pty_session(
+    base_url: str, headers: dict[str, str], session_id: str, *, timeout: timedelta
+) -> None:
+    """Best-effort teardown of a finished PTY session; errors are ignored."""
+    try:
+        httpx.delete(
+            f"{base_url}/pty/{session_id}",
+            headers=headers,
+            timeout=timeout.total_seconds(),
+        )
+    except httpx.HTTPError:
+        pass
+
+
+@contextmanager
+def _raw_mode(fd: int) -> Iterator[None]:
+    import termios
+    import tty
+
+    old = termios.tcgetattr(fd)
+    tty.setraw(fd)
+    try:
+        yield
+    finally:
+        termios.tcsetattr(fd, termios.TCSADRAIN, old)
+
+
+def _make_stdin_reader(fd: int) -> ReadFn:
+    """Build a cancellable stdin read driven by event-loop readability.
+
+    A blocking ``os.read`` in the default executor cannot be cancelled: the
+    worker thread stays parked in ``read(2)`` and stalls event-loop shutdown
+    until a key arrives. A reader callback is cancelled with its task.
+    """
+
+    async def stdin_read() -> bytes:
+        loop = asyncio.get_running_loop()
+        future: asyncio.Future[bytes] = loop.create_future()
+
+        def _on_readable() -> None:
+            if future.done():
+                return
+            try:
+                future.set_result(os.read(fd, 4096))
+            except BlockingIOError:
+                return  # Spurious wakeup; stay registered.
+            except OSError:
+                future.set_result(b"")  # EOF or hang-up.
+
+        loop.add_reader(fd, _on_readable)
+        try:
+            return await future
+        finally:
+            loop.remove_reader(fd)
+
+    return stdin_read
+
+
+def _posix_tty_io() -> tuple[ReadFn, WriteFn, SizeFn, int]:
+    """Build TTY stdin/stdout/size hooks plus the stdin fd for raw mode."""
+    stdin_fd = sys.stdin.fileno()
+    stdout: IO[bytes] = sys.stdout.buffer
+    stdin_read = _make_stdin_reader(stdin_fd)
+
+    def stdout_write(data: bytes) -> None:
+        stdout.write(data)
+        stdout.flush()
+
+    def get_size() -> tuple[int, int]:
+        size = os.get_terminal_size(stdin_fd)
+        return size.columns, size.lines
+
+    return stdin_read, stdout_write, get_size, stdin_fd
+
+
+def _consume_task_result(task: asyncio.Future) -> None:
+    """Retrieve a fire-and-forget task's outcome to suppress task warnings."""
+    if not task.cancelled():
+        task.exception()
+
+
+async def _pump_stdin(
+    ws: WSDuplex, send_lock: asyncio.Lock, stdin_read: ReadFn
+) -> None:
+    """Forward local stdin to the PTY as binary frames until EOF or close."""
+    while True:
+        data = await stdin_read()
+        if not data:
+            return
+        try:
+            async with send_lock:
+                await ws.send(bytes([BIN_STDIN]) + data)
+        except websockets.ConnectionClosed:
+            return
+
+
+async def stream_pty(
+    ws: WSDuplex,
+    *,
+    stdin_read: ReadFn,
+    stdout_write: WriteFn,
+    error_write: WriteFn | None = None,
+    send_lock: asyncio.Lock | None = None,
+) -> tuple[int | None, list[str]]:
+    """Relay frames; the exit code is ``None`` without an ``exit`` frame."""
+    exit_code: int | None = None
+    errors: list[str] = []
+
+    async def read_ws() -> None:
+        nonlocal exit_code
+        try:
+            async for message in ws:
+                if isinstance(message, bytes) and message:
+                    kind, payload = message[0], message[1:]
+                    if kind == BIN_REPLAY:
+                        if len(payload) <= 8:
+                            continue
+                        payload = payload[8:]
+                    if payload and kind in (BIN_STDOUT, BIN_STDERR, BIN_REPLAY):
+                        stdout_write(payload)
+                elif isinstance(message, str):
+                    try:
+                        frame = json.loads(message)
+                    except json.JSONDecodeError:
+                        continue
+                    frame_type = frame.get("type")
+                    if frame_type == "exit":
+                        exit_code = int(frame.get("exit_code") or 0)
+                        return
+                    if frame_type == "error":
+                        message = str(frame.get("error") or "unknown error")
+                        errors.append(message)
+                        if error_write is not None:
+                            # The terminal is in raw mode: CRLF, not LF.
+                            error_write(message.encode() + b"\r\n")
+        except websockets.ConnectionClosed:
+            # Abnormal close: keep the collected exit state and errors so the
+            # caller can surface them (e.g. execd's START_FAILED closes
+            # without a WebSocket close frame).
+            pass
+
+    stdin_task = asyncio.create_task(
+        _pump_stdin(ws, send_lock or asyncio.Lock(), stdin_read)
+    )
+    try:
+        # Give the stdin pump a head start before the read loop drains frames.
+        await asyncio.sleep(0)
+        # A local stdin EOF must not cut the output stream: reap the pump and
+        # keep reading until the server sends ``exit`` or closes.
+        await read_ws()
+    finally:
+        stdin_task.cancel()
+        await asyncio.gather(stdin_task, return_exceptions=True)
+    return exit_code, errors
+
+
+async def _connect_and_stream(
+    ws_url: str,
+    headers: dict[str, str],
+    *,
+    stdin_read: ReadFn,
+    stdout_write: WriteFn,
+    get_size: SizeFn,
+    error_write: WriteFn | None = None,
+    on_connected: Callable[[], None] | None = None,
+) -> tuple[int | None, list[str]]:
+    """Connect to the PTY WebSocket, drive the relay loop, handle resize."""
+    async with websockets.connect(ws_url, additional_headers=headers or None) as ws:
+        if on_connected is not None:
+            on_connected()
+        # websockets forbids concurrent sends: stdin frames and SIGWINCH
+        # resize frames share one lock, and fire-and-forget resize tasks get
+        # their results consumed so failures never surface as task warnings.
+        send_lock = asyncio.Lock()
+
+        async def send_frame(frame: str) -> None:
+            try:
+                async with send_lock:
+                    await ws.send(frame)
+            except websockets.ConnectionClosed:
+                pass
+
+        async def send_resize() -> None:
+            try:
+                cols, rows = get_size()
+            except OSError:
+                return
+            await send_frame(json.dumps({"type": "resize", "cols": cols, "rows": rows}))
+
+        await send_resize()
+        loop = asyncio.get_running_loop()
+        has_winch = hasattr(signal, "SIGWINCH")
+        if has_winch:
+            try:
+                loop.add_signal_handler(
+                    signal.SIGWINCH,
+                    lambda: asyncio.ensure_future(send_resize()).add_done_callback(
+                        _consume_task_result
+                    ),
+                )
+            except NotImplementedError:  # pragma: no cover - platform guard
+                has_winch = False
+        try:
+            return await stream_pty(
+                ws,
+                stdin_read=stdin_read,
+                stdout_write=stdout_write,
+                error_write=error_write,
+                send_lock=send_lock,
+            )
+        finally:
+            if has_winch:
+                loop.remove_signal_handler(signal.SIGWINCH)
+
+
+def _require_posix_tty() -> None:
+    if os.name != "posix":
+        raise click.ClickException(
+            "osb terminal is only supported on Unix, macOS, and Linux."
+        )
+    if not sys.stdin.isatty() or not sys.stdout.isatty():
+        raise click.ClickException("osb terminal requires an interactive TTY.")
+
+
+@click.command(
+    "terminal",
+    help="Open an interactive terminal into a sandbox via the execd PTY.",
+    epilog=(
+        "The shell runs inside the sandbox; exit it (or press Ctrl-D) to leave. "
+        "The remote exit code becomes this command's exit code."
+    ),
+)
+@click.argument("sandbox_id")
+@click.option("-w", "--workdir", default=None, help="Initial working directory.")
+@click.pass_obj
+@handle_errors
+def terminal(
+    obj: ClientContext,
+    sandbox_id: str,
+    workdir: str | None,
+) -> None:
+    """Open an interactive terminal into a sandbox."""
+    _require_posix_tty()
+
+    sandbox = obj.connect_sandbox(sandbox_id)
+    try:
+        endpoint = sandbox.get_endpoint(DEFAULT_EXECD_PORT)
+    finally:
+        sandbox.close()
+
+    headers = endpoint.build_request_headers(obj.connection_config)
+    protocol = obj.connection_config.protocol
+    base = _execd_base(endpoint.endpoint)
+    http_base = f"{protocol}://{base}"
+    ws_url = f"{_ws_scheme(protocol)}://{base}"
+
+    timeout = timedelta(seconds=obj.resolved_config.get("request_timeout", 30))
+    session_id = _create_pty_session(
+        http_base, headers, workdir=workdir, timeout=timeout
+    )
+
+    stdin_read, stdout_write, get_size, stdin_fd = _posix_tty_io()
+
+    def report_error(data: bytes) -> None:
+        # CRLF line endings are added by the sender: the terminal is in raw
+        # mode, where a bare LF does not return the carriage.
+        sys.stderr.buffer.write(data)
+        sys.stderr.buffer.flush()
+
+    exit_code: int | None = None
+    errors: list[str] = []
+    teardown = False
+    connected = False
+
+    def mark_connected() -> None:
+        nonlocal connected
+        connected = True
+
+    try:
+        with _raw_mode(stdin_fd):
+            exit_code, errors = asyncio.run(
+                _connect_and_stream(
+                    f"{ws_url}/pty/{session_id}/ws",
+                    headers,
+                    stdin_read=stdin_read,
+                    stdout_write=stdout_write,
+                    get_size=get_size,
+                    error_write=report_error,
+                    on_connected=mark_connected,
+                )
+            )
+        teardown = exit_code is not None or bool(errors)
+    except websockets.InvalidStatus as exc:
+        raise click.ClickException(
+            f"The execd refused the terminal connection: {exc}"
+        ) from exc
+    except (OSError, websockets.WebSocketException) as exc:
+        raise click.ClickException(f"Terminal connection failed: {exc}") from exc
+    finally:
+        # Clean exit tears the session down, as does a reported failure (e.g.
+        # START_FAILED: the shell never ran, so there is nothing to preserve)
+        # or a WebSocket that never opened (the shell starts on the first
+        # one). A lost connection on a live shell is the one case worth keeping.
+        if teardown or not connected:
+            _delete_pty_session(http_base, headers, session_id, timeout=timeout)
+
+    if exit_code is None:
+        if errors:
+            raise click.ClickException("Shell startup failed: " + "; ".join(errors))
+        sys.stderr.write(
+            "Warning: the terminal connection closed before the shell exited.\n"
+            f"The PTY session was kept on the sandbox: {session_id}\n"
+            f"  status: GET    {http_base}/pty/{session_id}\n"
+            f"  remove: DELETE {http_base}/pty/{session_id}\n"
+        )
+        sys.stderr.flush()
+        raise click.ClickException("Terminal connection lost.")
+    sys.exit(exit_code)

{opensandbox_cli-1.1.2.dev2026102001 → opensandbox_cli-1.2.1}/src/opensandbox_cli/config.py

@@ -28,6 +28,8 @@ import sys
 from pathlib import Path
 from typing import Any
 
+import click
+
 if sys.version_info >= (3, 11):
     import tomllib
 else:
@@ -49,6 +51,7 @@ DEFAULT_CONFIG_TEMPLATE = """\
 # domain = "localhost:8080"
 # protocol = "http"
 # request_timeout = 30
+# use_server_proxy is deprecated (maintenance mode); prefer the ingress gateway for data-plane traffic.
 # use_server_proxy = false
 
 [output]
@@ -64,14 +67,38 @@ def load_config_file(config_path: Path | None = None) -> dict[str, Any]:
     """Load and parse the TOML config file.
 
     Returns an empty dict if the file doesn't exist or tomllib is unavailable.
+    Raises ``click.ClickException`` if the file cannot be read or parsed.
     """
     path = config_path or DEFAULT_CONFIG_PATH
-    if not path.exists():
-        return {}
     if tomllib is None:
         return {}
-    with open(path, "rb") as f:
-        return tomllib.load(f)
+    # Open directly instead of checking path.exists() first: exists() raises
+    # PermissionError for a path under a directory that cannot be searched.
+    try:
+        with open(path, "rb") as f:
+            return tomllib.load(f)
+    except (FileNotFoundError, NotADirectoryError):
+        return {}
+    except OSError as exc:
+        raise click.ClickException(f"Cannot read config file {path}: {exc}") from exc
+    except (tomllib.TOMLDecodeError, UnicodeDecodeError) as exc:
+        raise click.ClickException(
+            f"Config file is not valid TOML ({path}): {exc}"
+        ) from exc
+
+
+# Config-file keys resolve_config reads as text. `config set` stores their
+# values verbatim: inferring a TOML number would rewrite an API key such as
+# "007123" as 7123.
+STRING_KEYS = frozenset(
+    {
+        "connection.api_key",
+        "connection.domain",
+        "connection.protocol",
+        "defaults.image",
+        "defaults.timeout",
+    }
+)
 
 
 def resolve_config(
@@ -92,10 +119,15 @@ def resolve_config(
     declared type.
 
     Keys returned:
-      - api_key, domain, protocol, request_timeout (int seconds), use_server_proxy (bool)
+      - api_key, domain, protocol, request_timeout (int seconds), use_server_proxy (bool; deprecated)
       - default_image, default_timeout (str like "10m")
     """
     file_cfg = load_config_file(config_path)
+    for section in ("connection", "output", "defaults"):
+        if section in file_cfg and not isinstance(file_cfg[section], dict):
+            raise click.ClickException(
+                f"Config section '{section}' must be a TOML table (use [{section}])."
+            )
     conn = file_cfg.get("connection", {})
     output_cfg = file_cfg.get("output", {})
     defaults = file_cfg.get("defaults", {})
@@ -111,10 +143,11 @@ def resolve_config(
         or os.getenv("OPEN_SANDBOX_PROTOCOL")
         or _str_or_none(conn.get("protocol"))
         or "http",
-        "request_timeout": cli_timeout
-        or _int_or_none(os.getenv("OPEN_SANDBOX_REQUEST_TIMEOUT"))
-        or _int_or_none(conn.get("request_timeout"))
-        or 30,
+        "request_timeout": _request_timeout_seconds(
+            cli_timeout,
+            _int_or_none(os.getenv("OPEN_SANDBOX_REQUEST_TIMEOUT")),
+            _int_or_none(conn.get("request_timeout")),
+        ),
         "use_server_proxy": _coalesce(
             cli_use_server_proxy,
             _bool_or_none(os.getenv("OPEN_SANDBOX_USE_SERVER_PROXY")),
@@ -139,6 +172,26 @@ def init_config_file(config_path: Path | None = None, *, force: bool = False) ->
     return path
 
 
+def _request_timeout_seconds(*candidates: int | None) -> int:
+    """Return the first explicit request timeout, in seconds.
+
+    ``None`` means that source did not set a timeout. Zero and negative values
+    are explicit and invalid: they must not fall through to a later source or
+    the 30 second default. ``--request-timeout 0`` used to be ignored because
+    ``0`` is falsy.
+    """
+    for value in candidates:
+        if value is None:
+            continue
+        if value <= 0:
+            raise click.ClickException(
+                "Request timeout must be a positive number of seconds, "
+                f"got {value}."
+            )
+        return value
+    return 30
+
+
 def _int_or_none(value: Any) -> int | None:
     """Coerce a configured value to ``int``, or ``None`` when it is not numeric."""
     if value is None or isinstance(value, bool):

{opensandbox_cli-1.1.2.dev2026102001 → opensandbox_cli-1.2.1}/src/opensandbox_cli/main.py

@@ -35,7 +35,8 @@ from opensandbox_cli.commands.sandbox import sandbox_group
 from opensandbox_cli.commands.skills import skills_group
 from opensandbox_cli.commands.snapshot import snapshot_group
 from opensandbox_cli.commands.template import template_group
-from opensandbox_cli.config import resolve_config
+from opensandbox_cli.commands.terminal import terminal
+from opensandbox_cli.config import _request_timeout_seconds, resolve_config
 
 BANNER = r"""[bold cyan]
    ____                   _____                 _ _
@@ -103,7 +104,10 @@ class BannerGroup(click.Group):
 @click.option(
     "--use-server-proxy/--no-use-server-proxy",
     default=None,
-    help="Route execd and endpoint traffic through the sandbox server proxy.",
+    help=(
+        "DEPRECATED: the server proxy is in maintenance mode (security/bugfix only); "
+        "route data-plane traffic through the ingress gateway instead."
+    ),
 )
 @click.option("--config", "config_path", type=click.Path(exists=False, path_type=Path), default=None, help="Config file path.")
 @click.option("-v", "--verbose", is_flag=True, default=False, help="Enable verbose/debug output.")
@@ -140,7 +144,7 @@ def cli(
             "api_key": api_key,
             "domain": domain,
             "protocol": protocol or "http",
-            "request_timeout": request_timeout or 30,
+            "request_timeout": _request_timeout_seconds(request_timeout),
             "use_server_proxy": use_server_proxy if use_server_proxy is not None else False,
             "color": True,
             "default_image": None,
@@ -157,6 +161,14 @@ def cli(
         )
     resolved["color"] = not no_color and resolved.get("color", True)
 
+    if ctx.invoked_subcommand != "config" and resolved.get("use_server_proxy"):
+        click.echo(
+            "Warning: connection.use_server_proxy is deprecated: the server proxy "
+            "data path is in maintenance mode (security and bug fixes only); route "
+            "data-plane traffic through the ingress gateway instead.",
+            err=True,
+        )
+
     effective_config_path = config_path or Path.home() / ".opensandbox" / "config.toml"
     ctx.obj = ClientContext(
         resolved_config=resolved,
@@ -170,6 +182,7 @@ cli.add_command(sandbox_group)
 cli.add_command(template_group)
 cli.add_command(snapshot_group)
 cli.add_command(command_group)
+cli.add_command(terminal)
 cli.add_command(file_group)
 cli.add_command(egress_group)
 cli.add_command(credential_vault_group)

{opensandbox_cli-1.1.2.dev2026102001 → opensandbox_cli-1.2.1}/src/opensandbox_cli/output.py

@@ -32,6 +32,7 @@ except ImportError:  # pragma: no cover
 from pydantic import BaseModel
 from rich import box
 from rich.console import Console
+from rich.markup import escape
 from rich.panel import Panel
 from rich.status import Status
 from rich.table import Table
@@ -116,7 +117,7 @@ class OutputFormatter:
             return
         if self.color:
             console = self._err_console if stderr else self.console
-            console.print(f"  [bold {style}]{icon} {msg}[/]")
+            console.print(f"  [bold {style}]{icon} {escape(msg)}[/]")
         else:
             click.echo(f"{plain}: {msg}", err=stderr)
 
@@ -143,7 +144,7 @@ class OutputFormatter:
             self._err_console.print(f"  [bold red]{title}[/]")
             self._err_console.print(f"  [dim]{'─' * (len(title) + 2)}[/]")
             for line in msg.splitlines():
-                self._err_console.print(f"  {line}")
+                self._err_console.print(f"  {escape(line)}")
             self._err_console.print()
         else:
             click.echo(f"ERROR [{title}]: {msg}", err=True)
@@ -152,7 +153,7 @@ class OutputFormatter:
     def spinner(self, msg: str) -> Generator[Status, None, None]:
         """Context manager that shows a spinner while work is in progress."""
         if self.color and self.fmt == "table":
-            with self._err_console.status(f"[bold cyan]⏳ {msg}[/]", spinner="dots") as status:
+            with self._err_console.status(f"[bold cyan]⏳ {escape(msg)}[/]", spinner="dots") as status:
                 yield status
         else:
             yield None  # type: ignore[arg-type]
@@ -161,7 +162,7 @@ class OutputFormatter:
         """Print content inside a styled panel."""
         if self.color:
             self.console.print(Panel(
-                content,
+                Text(content),
                 title=title,
                 title_align="left",
                 border_style=style,
@@ -187,7 +188,7 @@ class OutputFormatter:
             self.console.print(f"  [bold green]✓ {title}[/]")
             self.console.print(f"  [dim]{'─' * (len(title) + 2)}[/]")
             for k, v in data.items():
-                self.console.print(f"  [bold]{k}:[/] [cyan]{v}[/]")
+                self.console.print(f"  [bold]{escape(str(k))}:[/] [cyan]{escape(str(v))}[/]")
             self.console.print()
         else:
             click.echo(f"--- {title} ---")
@@ -316,10 +317,11 @@ class OutputFormatter:
         for row in rows:
             cells: list[Text | str] = []
             for col in columns:
-                val = str(row.get(col, "-"))
+                raw = row.get(col)
+                val = "-" if raw is None else str(raw)
                 if col in _STATUS_COLUMNS:
                     cells.append(_style_value(col, val))
                 else:
-                    cells.append(val)
+                    cells.append(Text(val))
             table.add_row(*cells)
         self.console.print(table)

{opensandbox_cli-1.1.2.dev2026102001 → opensandbox_cli-1.2.1}/src/opensandbox_cli/skills/opensandbox-sandbox-lifecycle.md

@@ -140,7 +140,8 @@ If the user does not specify an image, recommend one that matches the runtime th
 Templates are golden-image builds. The build is asynchronous: `template create` returns a template in `Pending`; poll `template get` until the phase is `Succeeded` (or `Failed`).
 
 ```bash
-osb template create --image python:3.12 --publish s3://bucket/publish -o json
+osb template create --image python:3.12 --publish s3://bucket/publish --format native -o json
+osb template create --image python:3.12 --publish oci://registry.example.com/sandbox/templates --format overlaybd -o json
 osb template create -f template-request.json -o json
 osb template get <template-id> -o json
 osb template list -o json
@@ -149,6 +150,8 @@ osb template delete <template-id> -o json
 
 Useful `template create` options: `--resource cpu=1 memory=512Mi disk=2Gi`, `--entrypoint` (repeat per argv item), `--env KEY=VALUE`, `--metadata KEY=VALUE`, `--format native|overlaybd`, `--readiness-probe tcp://127.0.0.1:44772`, `--warmup-seconds 60`. `-f <request-file>` reads the full request as public `CreateTemplateRequest` JSON (camelCase: `image`, `publish`, `resourceLimits`, `entrypoint`, `env`, `metadata`, `format`, `readiness.probe`, `readiness.warmupSeconds`), mutually exclusive with those flags.
 
+OCI publication requires a repository-only target without a tag or digest, `overlaybd` format, and a server-configured `.dockerconfigjson` Secret (`kubernetes.template_oci_publish_secret`). Sandbox creation also requires an OCI-enabled Fast Sandbox pool and the OverlayBD node daemon. S3 publication uses `native`. Wait for `Succeeded` before creating a sandbox; the server uses the immutable OCI manifest reference for OCI templates.
+
 Create a sandbox from a succeeded template:
 
 ```bash
@@ -320,7 +323,7 @@ osb sandbox health <sandbox-id> -o json
 Build a template, wait for it, and create from it:
 
 ```bash
-osb template create --image python:3.12 --publish s3://bucket/publish -o json
+osb template create --image python:3.12 --publish s3://bucket/publish --format native -o json
 osb template get <template-id> -o json
 osb sandbox create --template <template-id> --timeout 30m -o json
 osb sandbox health <sandbox-id> -o json

{opensandbox_cli-1.1.2.dev2026102001 → opensandbox_cli-1.2.1}/src/opensandbox_cli/utils.py

@@ -43,7 +43,10 @@ def parse_duration(value: str) -> timedelta:
         raise click.BadParameter("Duration cannot be empty")
 
     if value.isdigit():
-        return timedelta(seconds=int(value))
+        try:
+            return timedelta(seconds=int(value))
+        except (OverflowError, ValueError) as exc:
+            raise click.BadParameter(f"Duration '{value}' is out of range") from exc
 
     m = _DURATION_RE.match(value)
     if not m or not m.group(0):
@@ -51,10 +54,13 @@ def parse_duration(value: str) -> timedelta:
             f"Invalid duration '{value}'. Use format like 10m, 1h30m, 90s."
         )
 
-    hours = int(m.group("hours") or 0)
-    minutes = int(m.group("minutes") or 0)
-    seconds = int(m.group("seconds") or 0)
-    return timedelta(hours=hours, minutes=minutes, seconds=seconds)
+    try:
+        hours = int(m.group("hours") or 0)
+        minutes = int(m.group("minutes") or 0)
+        seconds = int(m.group("seconds") or 0)
+        return timedelta(hours=hours, minutes=minutes, seconds=seconds)
+    except (OverflowError, ValueError) as exc:
+        raise click.BadParameter(f"Duration '{value}' is out of range") from exc
 
 
 def parse_nullable_duration(value: str) -> timedelta | None:
@@ -80,12 +86,9 @@ class DurationType(click.ParamType):
             return value
         try:
             return parse_duration(value)
-        except click.BadParameter:
-            self.fail(
-                f"Invalid duration '{value}'. Use format like 10m, 1h30m, 90s.",
-                param,
-                ctx,
-            )
+        except click.BadParameter as exc:
+            # Keep the specific reason (empty, malformed, out of range).
+            self.fail(exc.format_message(), param, ctx)
 
 
 DURATION = DurationType()
@@ -199,7 +202,7 @@ def handle_errors(fn):  # type: ignore[no-untyped-def]
                     output.error_panel(str(exc), title="Sandbox Error")
                 else:
                     output.error_panel(
-                        f"{str(exc)}\n\n[dim]Type: {type(exc).__qualname__}[/]",
+                        f"{exc}\n\nType: {type(exc).__qualname__}",
                         title=type(exc).__name__,
                     )
             else: