solari-runloop-compat 0.1.0__py3-none-any.whl

solari_runloop/__init__.py

@@ -0,0 +1,42 @@
+"""Runloop-compatible interface over the Solari sandbox gateway.
+
+Not affiliated with Runloop. See COMPAT.md for exactly which parts of the Runloop SDK are supported.
+Change ``from runloop_api_client import RunloopSDK`` to ``from solari_runloop import RunloopSDK``.
+"""
+
+from __future__ import annotations
+
+from . import types
+from ._branding import TARGET_RUNLOOP_VERSION
+from ._client import AsyncRunloop, Runloop
+from ._exceptions import (
+    APIError,
+    APIStatusError,
+    ConflictError,
+    NotFoundError,
+    RateLimitError,
+    RunloopError,
+    BadRequestError,
+    APITimeoutError,
+    APIConnectionError,
+    AuthenticationError,
+    InternalServerError,
+    PermissionDeniedError,
+    SolariCompatUnsupported,
+    UnprocessableEntityError,
+    APIResponseValidationError,
+)
+from .lib.polling import PollingConfig, PollingTimeout
+from .sdk import AsyncRunloopSDK, RunloopSDK
+
+__version__ = "0.1.0"
+Client = Runloop
+AsyncClient = AsyncRunloop
+
+__all__ = [
+    "Runloop", "AsyncRunloop", "RunloopSDK", "AsyncRunloopSDK", "Client", "AsyncClient",
+    "RunloopError", "APIError", "APIStatusError", "APIConnectionError", "APITimeoutError",
+    "APIResponseValidationError", "BadRequestError", "AuthenticationError", "PermissionDeniedError",
+    "NotFoundError", "ConflictError", "UnprocessableEntityError", "RateLimitError", "InternalServerError",
+    "SolariCompatUnsupported", "PollingConfig", "PollingTimeout", "types", "TARGET_RUNLOOP_VERSION",
+]

solari_runloop/_branding.py

@@ -0,0 +1,10 @@
+"""Every name that might change after the naming/legal review lives here."""
+
+PACKAGE_NAME = "solari-runloop-compat"
+MODULE_NAME = "solari_runloop"
+#: Runloop SDK release whose public surface this layer mirrors (see COMPAT.md).
+TARGET_RUNLOOP_VERSION = "2.0.0"
+DEFAULT_BASE_URL = "https://api.getsolari.com"
+KEY_ENV_VARS = ("SOLARI_API_KEY", "RUNLOOP_API_KEY")
+BASE_URL_ENV_VARS = ("SOLARI_BASE_URL", "RUNLOOP_BASE_URL")
+KEY_PREFIX = "slr_"

solari_runloop/_client.py

@@ -0,0 +1,107 @@
+"""``Runloop`` / ``AsyncRunloop``: the REST-style client (``client.devboxes.*``)."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+from . import _config
+from ._gateway import Gateway
+from ._loop import LoopThread
+from ._resources import AsyncBlueprints, AsyncDevboxes, AsyncSecrets, _Unsupported
+from ._sync import SyncMirror
+
+DEFAULT_MAX_RETRIES = 5
+
+_UNSUPPORTED_RESOURCES = {
+    "objects": "Storage objects have no Solari equivalent yet.",
+    "agents": "Agents are a Runloop platform feature.",
+    "axons": "Axons are a Runloop platform feature.",
+    "network_policies": "Network policies have no Solari equivalent.",
+    "gateway_configs": "Agent gateways are a Runloop platform feature.",
+    "mcp_configs": "MCP configs are a Runloop platform feature.",
+    "accounts": "Accounts are a Runloop platform feature.",
+    "apikeys": "API keys are managed in the Solari console.",
+    "restricted_keys": "Restricted keys are a Runloop platform feature.",
+    "pty": "PTY tunnels are not exposed through the compat layer.",
+}
+
+
+class AsyncRunloop:
+    """Async REST client. Accepts Runloop's constructor arguments; ``timeout``/``default_headers``/
+    ``http_client`` are accepted for source compatibility and not used."""
+
+    _solari_mirror = False
+
+    def __init__(
+        self,
+        *,
+        bearer_token: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Any = None,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Optional[Mapping[str, str]] = None,
+        default_query: Optional[Mapping[str, object]] = None,
+        http_client: Any = None,
+        **_ignored: Any,
+    ) -> None:
+        token, url = _config.resolve(bearer_token, base_url)
+        self.bearer_token = token
+        self.base_url = url
+        self.max_retries = max_retries
+        self._gw = Gateway(token=token, base_url=url, max_retries=max_retries)
+        self.devboxes = AsyncDevboxes(self._gw)
+        self.blueprints = AsyncBlueprints(self._gw)
+        self.secrets = AsyncSecrets(self._gw)
+        for name, hint in _UNSUPPORTED_RESOURCES.items():
+            setattr(self, name, _Unsupported(name, hint))
+
+    def with_options(self, **_: Any) -> "AsyncRunloop":
+        return self
+
+    async def close(self) -> None:
+        await self._gw.aclose()
+
+    async def __aenter__(self) -> "AsyncRunloop":
+        return self
+
+    async def __aexit__(self, *_exc: Any) -> None:
+        await self.close()
+
+
+class Runloop:
+    """Sync REST client: the async client driven from a background event loop (see ``_loop.py``)."""
+
+    def __init__(self, **kwargs: Any) -> None:
+        self._attach(AsyncRunloop(**kwargs), LoopThread())
+
+    @classmethod
+    def _wrapping(cls, inner: AsyncRunloop, loop: LoopThread) -> "Runloop":
+        """A sync view of an existing async client (used by ``RunloopSDK`` so both share one loop)."""
+        self = cls.__new__(cls)
+        self._attach(inner, loop)
+        return self
+
+    def _attach(self, inner: AsyncRunloop, loop: LoopThread) -> None:
+        self._loop = loop
+        self._inner = inner
+        self.bearer_token = self._inner.bearer_token
+        self.base_url = self._inner.base_url
+        self.max_retries = self._inner.max_retries
+        self.devboxes = SyncMirror(self._inner.devboxes, self._loop)
+        self.blueprints = SyncMirror(self._inner.blueprints, self._loop)
+        self.secrets = SyncMirror(self._inner.secrets, self._loop)
+        for name in _UNSUPPORTED_RESOURCES:
+            setattr(self, name, getattr(self._inner, name))
+
+    def with_options(self, **_: Any) -> "Runloop":
+        return self
+
+    def close(self) -> None:
+        self._loop.run(self._inner.close())
+        self._loop.close()
+
+    def __enter__(self) -> "Runloop":
+        return self
+
+    def __exit__(self, *_exc: Any) -> None:
+        self.close()

solari_runloop/_config.py

@@ -0,0 +1,57 @@
+"""Credential and base-URL resolution: explicit argument, then SOLARI_*, then the RUNLOOP_* names."""
+
+from __future__ import annotations
+
+import logging
+import os
+from urllib.parse import urlparse
+from typing import Optional, Tuple
+
+from ._branding import DEFAULT_BASE_URL, KEY_PREFIX
+from ._exceptions import RunloopError
+
+log = logging.getLogger("solari_runloop")
+
+
+def _first_env(names: Tuple[str, ...]) -> Optional[str]:  # base URLs only; keys are handled in resolve()
+    for n in names:
+        v = os.environ.get(n)
+        if v:
+            return v
+    return None
+
+
+def _is_solari_host(url: str) -> bool:
+    host = (urlparse(url).hostname or "").lower()
+    return host == "getsolari.com" or host.endswith(".getsolari.com") or host in ("localhost", "127.0.0.1", "::1")
+
+
+def _env_base_url() -> Optional[str]:
+    """``SOLARI_BASE_URL`` is taken as given. ``RUNLOOP_BASE_URL`` (a Runloop variable, commonly ``https://api.runloop.ai``)
+    is only honoured for getsolari.com or loopback hosts: otherwise the Solari key would be sent to a third party."""
+    v = os.environ.get("SOLARI_BASE_URL")
+    if v:
+        return v
+    v = os.environ.get("RUNLOOP_BASE_URL")
+    if v and not _is_solari_host(v):
+        log.warning("Ignoring RUNLOOP_BASE_URL: its host is not a Solari host, and the Solari API key must not be sent there.")
+        return None
+    return v
+
+
+def resolve(bearer_token: Optional[str], base_url: Optional[str]) -> Tuple[str, str]:
+    """Key and base URL. A key that does not start with ``slr_`` is never used or sent: it is probably a Runloop key
+    (``Runloop(bearer_token=os.environ["RUNLOOP_API_KEY"])`` is a common pattern) and sending it would leak a third-party
+    secret. Sources are tried in order (argument, ``SOLARI_API_KEY``, ``RUNLOOP_API_KEY``); a non-``slr_`` one is skipped with a
+    warning that never prints the key, and if no ``slr_`` key remains this raises."""
+    for source, value in (("the bearer_token argument", bearer_token), ("SOLARI_API_KEY", os.environ.get("SOLARI_API_KEY")), ("RUNLOOP_API_KEY", os.environ.get("RUNLOOP_API_KEY"))):
+        if not value:
+            continue
+        if value.startswith(KEY_PREFIX):
+            url = str(base_url) if base_url else (_env_base_url() or DEFAULT_BASE_URL)
+            return value, url.rstrip("/")
+        log.warning("Ignoring %s: it does not start with %r, so it is not a Solari key and will not be sent to Solari.", source, KEY_PREFIX)
+    raise RunloopError(
+        "No Solari API key: pass bearer_token or set SOLARI_API_KEY to a key starting with 'slr_' "
+        "(keys from other services, including a Runloop RUNLOOP_API_KEY, are never sent to Solari)"
+    )

solari_runloop/_context.py

@@ -0,0 +1,91 @@
+"""Build contexts for ``COPY``/``ADD``.
+
+Runloop uploads a context directory as a *storage object*. Solari has no object store yet (GATEWAY-ENDPOINTS.md section 3), so until it does the
+context is kept in this process as a deterministic ``.tar.gz`` and embedded in the build recipe (``POST /templates`` bodies are capped at 1 MiB, so
+the context is capped at ~700 KB). When objects land, :class:`LocalContext` is replaced by a real upload and the recipe carries an object id instead.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import hashlib
+import io
+import os
+import tarfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional
+
+from . import _exceptions as ex
+
+MAX_CONTEXT_BYTES = 700_000
+
+
+@dataclass
+class LocalContext:
+    id: str
+    tar_gz: bytes
+    name: Optional[str] = None
+
+
+def _ignored(rel: str, patterns: List[str]) -> bool:
+    ignored = False
+    for pat in patterns:
+        neg = pat.startswith("!")
+        pat = pat.lstrip("!").strip("/")
+        if fnmatch.fnmatch(rel, pat) or fnmatch.fnmatch(rel, pat + "/*") or any(fnmatch.fnmatch(part, pat) for part in rel.split("/")):
+            ignored = not neg
+    return ignored
+
+
+def _make(entries: List[tuple], name: Optional[str]) -> LocalContext:
+    buf = io.BytesIO()
+    with tarfile.open(fileobj=buf, mode="w:gz", compresslevel=9) as tf:
+        for arc, path in entries:
+            info = tf.gettarinfo(str(path), arcname=arc)
+            info.mtime, info.uid, info.gid, info.uname, info.gname = 0, 0, 0, "", ""
+            if info.isreg():
+                with open(path, "rb") as fh:
+                    tf.addfile(info, fh)
+            else:
+                tf.addfile(info)
+    data = buf.getvalue()
+    if len(data) > MAX_CONTEXT_BYTES:
+        raise ex.SolariCompatUnsupported(
+            "Build contexts over ~700 KB compressed",
+            f"This context is {len(data)} bytes. Larger contexts need the gateway's storage objects; fetch big assets with RUN instead.",
+        )
+    return LocalContext(id="ctx_" + hashlib.sha256(data).hexdigest()[:16], tar_gz=data, name=name)
+
+
+def from_dir(path: str, *, name: Optional[str] = None, ignore: Optional[List[str]] = None) -> LocalContext:
+    root = Path(path)
+    patterns = list(ignore or [])
+    di = root / ".dockerignore"
+    if di.exists():
+        patterns += [ln.strip() for ln in di.read_text().splitlines() if ln.strip() and not ln.startswith("#")]
+    entries = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames.sort()
+        rel_dir = os.path.relpath(dirpath, root)
+        for n in sorted(dirnames + filenames):
+            full = Path(dirpath) / n
+            rel = n if rel_dir == "." else f"{rel_dir}/{n}"
+            if _ignored(rel, patterns):
+                if n in dirnames:
+                    dirnames.remove(n)
+                continue
+            entries.append((rel, full))
+    return _make(entries, name)
+
+
+def from_bytes(data: bytes, name: str = "file") -> LocalContext:
+    buf = io.BytesIO()
+    with tarfile.open(fileobj=buf, mode="w:gz") as tf:
+        info = tarfile.TarInfo(name)
+        info.size, info.mode = len(data), 0o644
+        tf.addfile(info, io.BytesIO(data))
+    b = buf.getvalue()
+    if len(b) > MAX_CONTEXT_BYTES:
+        raise ex.SolariCompatUnsupported("Build contexts over ~700 KB compressed", "Needs the gateway's storage objects.")
+    return LocalContext(id="ctx_" + hashlib.sha256(b).hexdigest()[:16], tar_gz=b, name=name)

solari_runloop/_dockerfile.py

@@ -0,0 +1,348 @@
+"""Dockerfile (a practical subset) -> Solari's ``CompiledImage`` build recipe.
+
+Solari builds a template by running ordered steps inside a VM cloned from a golden base and snapshotting the
+result, so a Dockerfile maps onto that recipe rather than onto an OCI image build. What is accepted is exactly what
+that model can do faithfully; everything else raises :class:`SolariCompatUnsupported` naming the instruction
+(BLUEPRINTS.md describes the full design and the path to arbitrary base images).
+
+Supported: ``FROM`` (one stage; ubuntu/debian-family or a Solari base/template), ``RUN``, ``ENV``, ``ARG`` (defaults and
+``--build-arg``), ``WORKDIR``, ``ENTRYPOINT``, ``CMD``, ``LABEL``/``EXPOSE``/``MAINTAINER`` (ignored), ``SHELL`` (bash only).
+Not yet: ``COPY``/``ADD`` (need build-context objects), multi-stage, ``USER``, ``VOLUME``, ``HEALTHCHECK``, ``ONBUILD``.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import posixpath
+import re
+import logging
+import shlex
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from . import _exceptions as ex
+
+log = logging.getLogger("solari_runloop")
+
+#: Image repositories that are Debian/Ubuntu userlands, which is what Solari's ``base`` golden is.
+DEBIAN_FAMILY = {"ubuntu", "debian"}
+#: Names that select a Solari golden base directly.
+SOLARI_BASES = {"base", "workstation"}
+
+#: Pinned build tool for image import (BLUEPRINTS.md, level 3a). The build FAILS if the checksum does not match.
+CRANE_VERSION = "v0.20.3"
+CRANE_SHA256 = "36c67a932f489b3f2724b64af90b599a8ef2aa7b004872597373c0ad694dc059"
+CRANE_URL = f"https://github.com/google/go-containerregistry/releases/download/{CRANE_VERSION}/go-containerregistry_Linux_x86_64.tar.gz"
+ROOT_DIR = "/srv/root"
+CONTEXT_DIR = "/tmp/solari-context"
+#: Registries the import accepts (public pulls only; there are no credentials in the build).
+REGISTRY_ALLOWLIST = ("docker.io", "index.docker.io", "registry-1.docker.io", "ghcr.io", "public.ecr.aws", "gcr.io", "quay.io", "mcr.microsoft.com")
+#: ``build_args`` switch that forces image import even for ubuntu/debian images (default: those use the native base).
+IMPORT_ARG = "SOLARI_IMPORT"
+
+_GUEST = Path(__file__).parent / "_guest"
+#: Runs a command inside the imported root (ENV and WORKDIR applied); installed into the builder, so into every
+#: devbox created from the template. The compat layer's exec wrapper calls it too.
+SOLARI_RUN = (_GUEST / "solari-run.sh").read_text()
+#: Validating tar extractor (see its docstring for the guards).
+SOLARI_EXTRACT = (_GUEST / "solari_extract.py").read_text()
+SOLARI_SIZECHECK = (_GUEST / "solari_sizecheck.py").read_text()
+#: Caps for one import: compressed layers (checked from the manifest before downloading), extracted bytes, wall clock.
+MAX_COMPRESSED_BYTES = 2 << 30
+MAX_EXTRACTED_BYTES = 4 << 30
+IMPORT_TIMEOUT_S = 900
+CRANE_BIN_SHA256 = "675f3b2f1696c1f6bc55b1ef535163364119776999f3d1471e4558ed35bab548"
+
+
+def logical_lines(text: str) -> List[Tuple[str, str]]:
+    """Join ``\\`` continuations, drop comments/blank lines, split into ``(INSTRUCTION, rest)``."""
+    out: List[Tuple[str, str]] = []
+    buf = ""
+    for raw in text.splitlines():
+        line = raw.rstrip()
+        if not buf and (not line.strip() or line.lstrip().startswith("#")):
+            continue
+        if buf and line.lstrip().startswith("#"):
+            continue
+        if line.endswith("\\"):
+            buf += line[:-1] + " "
+            continue
+        buf += line
+        stripped = buf.strip()
+        buf = ""
+        if stripped:
+            instr, _, rest = stripped.partition(" ")
+            out.append((instr.upper(), rest.strip()))
+    if buf.strip():
+        instr, _, rest = buf.strip().partition(" ")
+        out.append((instr.upper(), rest.strip()))
+    return out
+
+
+# Docker's default PATH, so `ENV PATH=/opt/x/bin:$PATH` expands to a usable value (an unknown $VAR is "").
+DEFAULT_PATH = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+
+
+def _subst(s: str, args: Dict[str, str]) -> str:
+    def rep(m: "re.Match[str]") -> str:
+        name = m.group(1) or m.group(2)
+        return args.get(name, "")
+
+    return re.sub(r"\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))", rep, s)
+
+
+def _json_or_shell(rest: str) -> List[str]:
+    rest = rest.strip()
+    if rest.startswith("["):
+        try:
+            v = json.loads(rest)
+            if isinstance(v, list) and all(isinstance(x, str) for x in v):
+                return v
+        except ValueError:
+            pass
+    return ["/bin/sh", "-c", rest]
+
+
+def _parse_env(rest: str) -> List[Tuple[str, str]]:
+    # ``ENV k=v k2="v 2"`` or the legacy ``ENV k v``.
+    if "=" not in rest.split(None, 1)[0]:
+        k, _, v = rest.partition(" ")
+        return [(k, v.strip().strip('"'))]
+    return [(t.partition("=")[0], t.partition("=")[2]) for t in shlex.split(rest)]
+
+
+def _registry_of(image: str) -> str:
+    first = image.split("/")[0]
+    return first if ("." in first or ":" in first) and "/" in image else "docker.io"
+
+
+def _resolve_from(rest: str, args: Dict[str, str]) -> Tuple[Optional[str], Optional[str], Optional[str]]:
+    """-> ``(base, from_template, import_image)`` for the CompiledImage."""
+    tokens = [t for t in rest.split() if not t.startswith("--")]
+    if "AS" in [t.upper() for t in tokens[1:]]:
+        raise ex.SolariCompatUnsupported("Multi-stage Dockerfile (FROM ... AS)", "Single-stage builds only.")
+    image = _subst(tokens[0], args)
+    repo = image.split("@", 1)[0]
+    if ":" in repo.split("/")[-1]:
+        repo = repo.rsplit(":", 1)[0]
+    if image == "scratch":
+        raise ex.SolariCompatUnsupported("FROM scratch")
+    parts = repo.split("/")
+    if len(parts) > 1 and ("." in parts[0] or ":" in parts[0] or parts[0] == "localhost"):
+        parts = parts[1:]  # registry host
+    if parts[:1] == ["library"]:
+        parts = parts[1:]
+    name = "/".join(parts)
+    force = args.get(IMPORT_ARG) not in (None, "", "0", "false")
+    if name in SOLARI_BASES:
+        return name, None, None
+    if name in DEBIAN_FAMILY and not force:
+        return "base", None, None
+    registry = _registry_of(image)
+    if registry not in REGISTRY_ALLOWLIST:
+        raise ex.SolariCompatUnsupported(
+            f"FROM {image}",
+            f"Image import only pulls public images from {', '.join(REGISTRY_ALLOWLIST)} (no registry credentials in builds).",
+        )
+    return None, None, image
+
+
+def compile_dockerfile(
+    dockerfile: Optional[str],
+    *,
+    system_setup_commands: Optional[List[str]] = None,
+    file_mounts: Optional[Dict[str, str]] = None,
+    base_blueprint_name: Optional[str] = None,
+    build_args: Optional[Dict[str, str]] = None,
+    context: Optional[bytes] = None,
+) -> Dict[str, Any]:
+    """Runloop blueprint-create inputs -> a ``CompiledImage`` dict for ``POST /templates``.
+
+    ``context`` is a ``.tar.gz`` build context for ``COPY``/``ADD`` (see ``_context.py``)."""
+    steps: List[Dict[str, Any]] = []
+    base: Optional[str] = None
+    from_template: Optional[str] = base_blueprint_name
+    args: Dict[str, str] = {"PATH": DEFAULT_PATH, **(build_args or {})}  # ARG + ENV, for $VAR substitution
+    arg_only: Dict[str, str] = dict(build_args or {})  # ARGs, exported into each RUN
+    seen_from = False
+    import_image: Optional[str] = None
+    workdir = "/"
+    context_loaded = False
+
+    for instr, rest in logical_lines(dockerfile or ""):
+        if instr == "FROM":
+            if seen_from:
+                raise ex.SolariCompatUnsupported("Multi-stage Dockerfile (second FROM)", "Single-stage builds only.")
+            seen_from = True
+            fb, ft, img = _resolve_from(rest, args)
+            if base_blueprint_name:
+                log.warning("base_blueprint_name %r overrides the Dockerfile FROM", base_blueprint_name)
+            else:
+                base, from_template, import_image = fb, ft, img
+                if import_image:
+                    log.warning(
+                        "FROM %s is imported into a chroot inside the builder VM (BLUEPRINTS.md level 3a): needs a shell in the image, "
+                        "~2 GB free disk, ENTRYPOINT/CMD are recorded but not started, public registries only.",
+                        import_image,
+                    )
+                    steps.extend(import_steps(import_image))
+        elif instr == "ARG":
+            k, eq, v = rest.partition("=")
+            k = k.strip()
+            args.setdefault(k, v.strip().strip('"') if eq else "")
+            arg_only[k] = args[k]
+        elif instr == "ENV":
+            for k, v in _parse_env(_subst(rest, args)):
+                if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", k):
+                    raise ex.SolariCompatUnsupported(f"ENV name {k!r}", "Environment variable names must match [A-Za-z_][A-Za-z0-9_]*.")
+                args[k] = v
+                steps.append({"op": "env", "key": k, "value": v})
+                if import_image:
+                    steps.append(_run(f"printf 'export %s=%s\\n' {shlex.quote(k)} {shlex.quote(shlex.quote(v))} >> /etc/solari-env"))
+        elif instr == "RUN":
+            cmd = " ".join(shlex.quote(a) for a in json.loads(rest)) if rest.startswith("[") else _subst_run(rest, arg_only)
+            steps.append(_run("solari-run " + shlex.quote(cmd)) if import_image else _run(cmd))
+        elif instr == "WORKDIR":
+            wd = _subst(rest, args)
+            wd = wd if wd.startswith("/") else posixpath.normpath(posixpath.join(workdir, wd))
+            workdir = wd
+            steps.append({"op": "workdir", "dir": wd})
+            if import_image:
+                steps.append(_run(f"echo {shlex.quote(wd)} > /etc/solari-workdir && solari-run {shlex.quote('mkdir -p ' + shlex.quote(wd))}"))
+        elif instr == "ENTRYPOINT":
+            cmdv = _json_or_shell(_subst(rest, args))
+            steps.append({"op": "entrypoint", "command": cmdv})
+            if import_image:
+                steps.append(_run(f"echo {shlex.quote(json.dumps(cmdv))} > /etc/solari-entrypoint"))
+        elif instr == "CMD":
+            cmdv = _json_or_shell(_subst(rest, args))
+            steps.append({"op": "cmd", "command": cmdv})
+            if import_image:
+                steps.append(_run(f"echo {shlex.quote(json.dumps(cmdv))} > /etc/solari-cmd"))
+        elif instr in ("LABEL", "EXPOSE", "MAINTAINER", "STOPSIGNAL"):
+            continue
+        elif instr == "SHELL":
+            if "bash" not in rest and "sh" not in rest:
+                raise ex.SolariCompatUnsupported("SHELL " + rest)
+        elif instr in ("COPY", "ADD"):
+            if context is None:
+                raise ex.SolariCompatUnsupported(instr, "No build_context was given. Upload one with sdk.storage_object.upload_from_dir(...) and pass build_context=obj.as_build_context().")
+            if not context_loaded:
+                steps.append(_context_step(context))
+                context_loaded = True
+            steps.append(_copy_step(instr, _subst(rest, args), workdir, bool(import_image)))
+        else:
+            raise ex.SolariCompatUnsupported(instr)
+
+    for cmd in system_setup_commands or []:
+        steps.append(_run("solari-run " + shlex.quote(cmd)) if import_image else _run(cmd))
+    for path, contents in (file_mounts or {}).items():
+        b64 = base64.b64encode(contents.encode()).decode()
+        dest = (ROOT_DIR + posixpath.normpath(path)) if import_image else path
+        steps.append(_run(f"mkdir -p \"$(dirname {shlex.quote(dest)})\" && echo {b64} | base64 -d > {shlex.quote(dest)}"))
+    if not seen_from and not from_template:
+        base = "base"
+    if context_loaded:
+        steps.append(_run(f"rm -rf {CONTEXT_DIR}"))
+    out: Dict[str, Any] = {"kind": "sandbox", "packages": [], "steps": steps, "fragment": "", "localFiles": []}
+    if from_template:
+        out["fromTemplate"] = from_template
+    else:
+        out["base"] = base or "base"
+    return out
+
+
+def _subst_run(cmd: str, args: Dict[str, str]) -> str:
+    """Docker expands ARG/ENV in RUN through the shell; here ENV becomes real env steps, so only ARGs need injecting."""
+    if not args:
+        return cmd
+    exports = " ".join(f"{k}={shlex.quote(v)}" for k, v in args.items() if re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", k))
+    return f"export {exports}; {cmd}" if exports else cmd
+
+
+def _run(command: str) -> Dict[str, Any]:
+    return {"op": "run", "command": command}
+
+
+def import_steps(image: str) -> List[Dict[str, Any]]:
+    """Build steps that pull ``image`` into ``/srv/root`` and install the ``solari-run`` wrapper."""
+    b64 = lambda text: base64.b64encode(text.encode()).decode()  # noqa: E731
+    img = shlex.quote(image)
+    crane_ok = f"echo '{CRANE_BIN_SHA256}  /usr/local/bin/crane' | sha256sum -c - >/dev/null || {{ echo 'solari: crane binary checksum mismatch' >&2; exit 1; }}"
+    size_check = f"python3 /usr/local/bin/solari-size-check \"$SOLARI_IMAGE\" {MAX_COMPRESSED_BYTES}"
+    return [
+        _run(
+            "set -e; mkdir -p /usr/local/bin; if [ ! -x /usr/local/bin/crane ]; then curl -fsSL " + shlex.quote(CRANE_URL) + " -o /tmp/crane.tgz && "
+            f"echo '{CRANE_SHA256}  /tmp/crane.tgz' | sha256sum -c - && tar -xzf /tmp/crane.tgz -C /usr/local/bin crane && rm -f /tmp/crane.tgz; fi; " + crane_ok
+        ),
+        _run(
+            f"echo {b64(SOLARI_EXTRACT)} | base64 -d > /usr/local/bin/solari-extract && echo {b64(SOLARI_SIZECHECK)} | base64 -d > /usr/local/bin/solari-size-check && "
+            "chmod 0755 /usr/local/bin/solari-extract /usr/local/bin/solari-size-check"
+        ),
+        # Build steps run under plain sh, so the pipeline (which needs pipefail) runs in an explicit bash.
+        _run(
+            "bash -c "
+            + shlex.quote(
+                "set -eo pipefail; " + crane_ok + f"; export DOCKER_CONFIG=$(mktemp -d) SOLARI_IMAGE={img}; "
+                + size_check
+                + f"; rm -rf {ROOT_DIR}; mkdir -p {ROOT_DIR}; "
+                f"timeout {IMPORT_TIMEOUT_S} crane export --platform linux/amd64 {img} - | python3 /usr/local/bin/solari-extract {ROOT_DIR} {MAX_EXTRACTED_BYTES}; "
+                'rm -rf "$DOCKER_CONFIG"; '
+                f"chroot {ROOT_DIR} /bin/sh -c true 2>/dev/null || {{ echo {shlex.quote('solari: image ' + image + ' has no /bin/sh; image import needs a shell (distroless images are not supported)')} >&2; exit 1; }}"
+            )
+        ),
+        _run(
+            f"echo {b64(SOLARI_RUN)} | base64 -d > /usr/local/bin/solari-run && chmod 0755 /usr/local/bin/solari-run && "
+            f"echo {ROOT_DIR} > /etc/solari-rootdir && : > /etc/solari-env && echo / > /etc/solari-workdir"
+        ),
+    ]
+
+
+_GLOB_SAFE = re.compile(r"[A-Za-z0-9_./*?\[\]+@%-]+")
+
+
+def _context_step(context: bytes) -> Dict[str, Any]:
+    return _run(f"rm -rf {CONTEXT_DIR} && mkdir -p {CONTEXT_DIR} && echo {base64.b64encode(context).decode()} | base64 -d | tar -xz -C {CONTEXT_DIR}")
+
+
+def _copy_step(instr: str, rest: str, workdir: str, imported: bool) -> Dict[str, Any]:
+    """``COPY``/``ADD`` from the extracted build context into the image (or, for an import, into the image root)."""
+    parts = shlex.split(rest) if not rest.startswith("[") else json.loads(rest)
+    flags = [p for p in parts if p.startswith("--")]
+    parts = [p for p in parts if not p.startswith("--")]
+    for f in flags:
+        if f.startswith("--from"):
+            raise ex.SolariCompatUnsupported(f"{instr} --from (multi-stage)")
+        if not (f.startswith("--chown=") or f.startswith("--chmod=")):
+            raise ex.SolariCompatUnsupported(f"{instr} {f.split('=')[0]}")
+    if len(parts) < 2:
+        raise ex.SolariCompatUnsupported(f"{instr} needs at least a source and a destination")
+    *srcs, dest = parts
+    for src in srcs:
+        if "://" in src:
+            raise ex.SolariCompatUnsupported(f"{instr} from a URL", "Download with RUN curl instead.")
+        if ".." in posixpath.normpath(src).split("/") or src.startswith("/"):
+            raise ex.SolariCompatUnsupported(f"{instr} source {src!r}", "Sources must be relative paths inside the build context.")
+    abs_dest = posixpath.normpath(dest if dest.startswith("/") else posixpath.join(workdir, dest))
+    if dest.endswith("/") or dest in (".", "./"):
+        abs_dest = abs_dest.rstrip("/") + "/"
+    real_dest = (ROOT_DIR + abs_dest) if imported else abs_dest
+    quoted = " ".join(s if _GLOB_SAFE.fullmatch(s) else shlex.quote(s) for s in srcs)
+    into_dir = dest.endswith("/") or len(srcs) > 1
+    q_dest = shlex.quote(real_dest)
+    unpack = instr == "ADD" and len(srcs) == 1 and re.search(r"\.(tar|tar\.gz|tgz)$", srcs[0]) is not None
+    if unpack:
+        body = f"mkdir -p {q_dest} && tar -xf {quoted} -C {q_dest}"
+    elif into_dir:
+        body = f"mkdir -p {q_dest} && cp -a -- {quoted} {q_dest}"
+    else:
+        body = f"mkdir -p \"$(dirname {q_dest})\" && cp -a -- {quoted} {q_dest}"
+    post = ""
+    for f in flags:
+        if f.startswith("--chown="):
+            who = f.split("=", 1)[1]
+            post += f" && (chown -R {shlex.quote(who)} {q_dest} 2>/dev/null || true)"
+        elif f.startswith("--chmod="):
+            post += f" && chmod -R {shlex.quote(f.split('=', 1)[1])} {q_dest}"
+    return _run(f"cd {CONTEXT_DIR} && {body}{post}")