cloudex 0.1.11__tar.gz

cloudex-0.1.11/.gitignore

@@ -0,0 +1,19 @@
+node_modules/
+dist/
+.wrangler/
+.dev.vars
+.env*
+!.env.example
+*.log
+.DS_Store
+
+# Go build output
+/go/bin/
+
+# Generated by scripts/bundle-api.sh
+/go/internal/deploy/assets/worker.js
+/go/internal/deploy/assets/meta.json
+
+# Python
+__pycache__/
+*.egg-info/

cloudex-0.1.11/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luis Catacora
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cloudex-0.1.11/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.5
+Name: cloudex
+Version: 0.1.11
+Summary: SDK for Cloudex: agent sandboxes in your own Cloudflare account
+Project-URL: Homepage, https://cloudex.build
+Project-URL: Source, https://github.com/lucataco/cloudex
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,claude-code,cloudflare,codex,containers,sandbox
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Cloudex SDK for Python
+
+Create, fork and drive [Cloudex](https://cloudex.build) sandboxes: agent
+computers in your own Cloudflare account. Python 3.9+, standard library only.
+
+```python
+from concurrent.futures import ThreadPoolExecutor
+from cloudex import Cloudex
+
+cx = Cloudex()  # the deployment saved by `cloudex login`
+box = cx.create(name="web")
+box.exec("git clone https://github.com/you/app && cd app && pip install -e .")
+
+# Ten copies of that disk, each trying something different.
+forks = box.fork(count=10, name="try")
+with ThreadPoolExecutor(10) as pool:
+    results = list(pool.map(lambda f: f.exec(["pytest", "-x", "app"]), forks))
+
+print(forks[0].host(8000))  # an HTTPS link to a port
+for f in forks:
+    f.delete()
+box.stop()  # saves the disk; box.resume() picks up where it left off
+```
+
+## Agents
+
+`box.prompt()` starts Claude Code, or Codex, on a task with no terminal. Each
+message is one turn of the agent's own conversation, which lives on the
+sandbox's disk.
+
+```python
+agent = box.prompt("make the tests pass", cwd="app")
+for e in agent.events():
+    # e["type"] is prompt, event (the agent's own JSON in e["event"]), output or end
+    if e["type"] == "event":
+        print(e["event"])
+print(agent.last_message, agent.error)
+
+agent.send("now update the docs")  # waits for a running turn
+agent.send("stop, fix the build first", interrupt=True)
+agent.wait()
+```
+
+`events()` waits up to 25 seconds per request, so give `Cloudex(timeout=)` more
+than that if you set one.
+
+## Connecting
+
+`Cloudex(api_url, api_key)` takes the API URL and key that `cloudex deploy`
+printed (`cloudex status --show-key` shows them again). Without them it reads
+`$CLOUDEX_API_URL` and `$CLOUDEX_API_KEY`, then the deployment the CLI saved.
+The key gives full control of your sandboxes.
+
+## API
+
+| Call | Does |
+|---|---|
+| `cx.create(name=, size=, idle_minutes=, env=, files=, repo=)` | Create a sandbox; returns once it's running (and the repo is cloned) |
+| `cx.get(ref)`, `cx.list()`, `cx.health()` | Look up by id or name, list, check the deployment |
+| `box.exec(cmd, root=, cwd=, timeout_sec=)` | Run shell code, or an argument list, and wait; check `exit_code` |
+| `box.fork(count=, name=, size=, idle_minutes=)` | Up to 10 sandboxes starting from a copy of the disk |
+| `box.host(port)` | HTTPS link to a port on your preview domain |
+| `box.desktop(size=)`, `box.stop_desktop()` | Start the desktop (Chrome, a terminal) and get a link to it |
+| `box.stop()`, `box.resume(from_backup=)`, `box.delete()` | Save and stop, start again, delete |
+| `box.refresh()` | Fetch the latest state; `box.id`, `box.name`, `box.state` and `box.info` hold it |
+| `box.settings()`, `box.update_settings(env=, files=)` | Environment variables and files the sandbox gets at every start; `None` removes one |
+| `cx.set_key(provider, key)`, `cx.list_keys()`, `cx.delete_key(provider)` | AI provider keys sandboxes use without holding them (`"anthropic"`, `"openai"`) |
+| `box.prompt(prompt, agent=, cwd=, model=)` | Start Claude Code (default) or Codex on a task; returns an `Agent` at once |
+| `box.agents()`, `box.agent(id)` | The sandbox's agents, newest first; one by id |
+| `agent.events(after=, follow=)` | Iterate over its events (dicts); follows until the agent is idle |
+| `agent.send(prompt, interrupt=)`, `agent.interrupt()`, `agent.wait()` | Continue, stop the running turn, wait until idle |
+
+Errors from the API raise `CloudexError`, with `status` and the API's message.
+The full API is described at `<your API URL>/v1/openapi.json`.
+
+Fetching a preview link with `urllib` needs a `User-Agent` header: Cloudflare's
+Browser Integrity Check, on by default for your domain, answers urllib's default
+one with error 1010.

cloudex-0.1.11/README.md

@@ -0,0 +1,78 @@
+# Cloudex SDK for Python
+
+Create, fork and drive [Cloudex](https://cloudex.build) sandboxes: agent
+computers in your own Cloudflare account. Python 3.9+, standard library only.
+
+```python
+from concurrent.futures import ThreadPoolExecutor
+from cloudex import Cloudex
+
+cx = Cloudex()  # the deployment saved by `cloudex login`
+box = cx.create(name="web")
+box.exec("git clone https://github.com/you/app && cd app && pip install -e .")
+
+# Ten copies of that disk, each trying something different.
+forks = box.fork(count=10, name="try")
+with ThreadPoolExecutor(10) as pool:
+    results = list(pool.map(lambda f: f.exec(["pytest", "-x", "app"]), forks))
+
+print(forks[0].host(8000))  # an HTTPS link to a port
+for f in forks:
+    f.delete()
+box.stop()  # saves the disk; box.resume() picks up where it left off
+```
+
+## Agents
+
+`box.prompt()` starts Claude Code, or Codex, on a task with no terminal. Each
+message is one turn of the agent's own conversation, which lives on the
+sandbox's disk.
+
+```python
+agent = box.prompt("make the tests pass", cwd="app")
+for e in agent.events():
+    # e["type"] is prompt, event (the agent's own JSON in e["event"]), output or end
+    if e["type"] == "event":
+        print(e["event"])
+print(agent.last_message, agent.error)
+
+agent.send("now update the docs")  # waits for a running turn
+agent.send("stop, fix the build first", interrupt=True)
+agent.wait()
+```
+
+`events()` waits up to 25 seconds per request, so give `Cloudex(timeout=)` more
+than that if you set one.
+
+## Connecting
+
+`Cloudex(api_url, api_key)` takes the API URL and key that `cloudex deploy`
+printed (`cloudex status --show-key` shows them again). Without them it reads
+`$CLOUDEX_API_URL` and `$CLOUDEX_API_KEY`, then the deployment the CLI saved.
+The key gives full control of your sandboxes.
+
+## API
+
+| Call | Does |
+|---|---|
+| `cx.create(name=, size=, idle_minutes=, env=, files=, repo=)` | Create a sandbox; returns once it's running (and the repo is cloned) |
+| `cx.get(ref)`, `cx.list()`, `cx.health()` | Look up by id or name, list, check the deployment |
+| `box.exec(cmd, root=, cwd=, timeout_sec=)` | Run shell code, or an argument list, and wait; check `exit_code` |
+| `box.fork(count=, name=, size=, idle_minutes=)` | Up to 10 sandboxes starting from a copy of the disk |
+| `box.host(port)` | HTTPS link to a port on your preview domain |
+| `box.desktop(size=)`, `box.stop_desktop()` | Start the desktop (Chrome, a terminal) and get a link to it |
+| `box.stop()`, `box.resume(from_backup=)`, `box.delete()` | Save and stop, start again, delete |
+| `box.refresh()` | Fetch the latest state; `box.id`, `box.name`, `box.state` and `box.info` hold it |
+| `box.settings()`, `box.update_settings(env=, files=)` | Environment variables and files the sandbox gets at every start; `None` removes one |
+| `cx.set_key(provider, key)`, `cx.list_keys()`, `cx.delete_key(provider)` | AI provider keys sandboxes use without holding them (`"anthropic"`, `"openai"`) |
+| `box.prompt(prompt, agent=, cwd=, model=)` | Start Claude Code (default) or Codex on a task; returns an `Agent` at once |
+| `box.agents()`, `box.agent(id)` | The sandbox's agents, newest first; one by id |
+| `agent.events(after=, follow=)` | Iterate over its events (dicts); follows until the agent is idle |
+| `agent.send(prompt, interrupt=)`, `agent.interrupt()`, `agent.wait()` | Continue, stop the running turn, wait until idle |
+
+Errors from the API raise `CloudexError`, with `status` and the API's message.
+The full API is described at `<your API URL>/v1/openapi.json`.
+
+Fetching a preview link with `urllib` needs a `User-Agent` header: Cloudflare's
+Browser Integrity Check, on by default for your domain, answers urllib's default
+one with error 1010.

cloudex-0.1.11/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cloudex"
+dynamic = ["version"]
+description = "SDK for Cloudex: agent sandboxes in your own Cloudflare account"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+keywords = ["sandbox", "agents", "cloudflare", "containers", "claude-code", "codex"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://cloudex.build"
+Source = "https://github.com/lucataco/cloudex"
+
+[tool.hatch.version]
+path = "src/cloudex/__init__.py"

cloudex-0.1.11/src/cloudex/__init__.py

@@ -0,0 +1,441 @@
+"""The Cloudex SDK: create, fork and drive sandboxes from Python.
+
+It talks to the /v1 API that `cloudex deploy` set up in your Cloudflare
+account, using only the standard library.
+
+    from cloudex import Cloudex
+
+    cx = Cloudex()  # the deployment saved by `cloudex login`, or $CLOUDEX_API_URL and $CLOUDEX_API_KEY
+    box = cx.create(name="web")
+    print(box.exec("uname -a").stdout)
+    forks = box.fork(count=3, name="try")
+
+    agent = box.prompt("make the tests pass")  # Claude Code, with no terminal
+    for event in agent.events():
+        print(event["type"])
+    print(agent.last_message)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, Iterator, List, Optional, Sequence, Union
+
+__all__ = ["Agent", "Cloudex", "CloudexError", "Desktop", "ExecResult", "Health", "ProviderKey", "Sandbox", "Settings"]
+__version__ = "0.1.11"
+
+
+class CloudexError(Exception):
+    """An error from the API, with its HTTP status (0 when there was no request)."""
+
+    def __init__(self, status: int, message: str):
+        super().__init__(message)
+        self.status = status
+        self.message = message
+
+
+@dataclass(frozen=True)
+class ExecResult:
+    exit_code: int
+    stdout: str  # each stream is cut at 1 MiB
+    stderr: str
+    timed_out: bool
+    ms: int
+
+
+@dataclass(frozen=True)
+class Desktop:
+    url: str  # the viewer, on the preview domain; anyone with it can use the desktop
+    port: int
+    path: str
+    size: str
+    installed: bool  # this call installed it (the first start takes a minute or two)
+    started: bool  # this call started it, rather than finding it running
+
+
+@dataclass(frozen=True)
+class ProviderKey:
+    provider: str  # anthropic or openai
+    hint: str  # the key's last 4 characters; the key itself is never returned
+    updated_at: int  # milliseconds since the epoch
+
+
+@dataclass(frozen=True)
+class Settings:
+    """A sandbox's settings. Values and file contents never come back."""
+
+    env: List[str]
+    files: List[str]  # as ~/path
+    repo: Optional[Dict[str, Any]]  # url, dir, branch
+
+
+@dataclass(frozen=True)
+class Health:
+    ok: bool
+    version: str
+    preview_zone: Optional[str]
+    backups: bool
+
+
+def _drop_none(**fields: Any) -> Dict[str, Any]:
+    return {k: v for k, v in fields.items() if v is not None}
+
+
+def _saved_deployment(config_dir: Optional[str]) -> Dict[str, Any]:
+    # The CLI keeps its deployment in ~/.config/cloudex/config.json.
+    path = Path(config_dir) if config_dir else Path.home() / ".config" / "cloudex"
+    try:
+        return json.loads((path / "config.json").read_text())
+    except (OSError, ValueError):
+        return {}
+
+
+class Cloudex:
+    """A Cloudex deployment.
+
+    The URL and key come from the arguments, then $CLOUDEX_API_URL and
+    $CLOUDEX_API_KEY, then the deployment saved by `cloudex deploy` or
+    `cloudex login`, the same order as the CLI. timeout is in seconds per
+    request; by default there's none, since starting or forking can take
+    minutes the first time on a host.
+    """
+
+    def __init__(self, api_url: Optional[str] = None, api_key: Optional[str] = None, timeout: Optional[float] = None):
+        url = api_url or os.environ.get("CLOUDEX_API_URL")
+        key = api_key or os.environ.get("CLOUDEX_API_KEY")
+        if not url or not key:
+            saved = _saved_deployment(os.environ.get("CLOUDEX_CONFIG_DIR"))
+            url = url or saved.get("apiUrl")
+            key = key or saved.get("apiKey")
+        if not url:
+            raise CloudexError(
+                0,
+                "no Cloudex deployment: pass api_url and api_key, set CLOUDEX_API_URL and CLOUDEX_API_KEY, or run cloudex login",
+            )
+        self.api_url = url.rstrip("/")
+        self._key = key or ""
+        self._timeout = timeout
+
+    def __repr__(self) -> str:
+        return f"Cloudex({self.api_url!r})"
+
+    def health(self) -> Health:
+        """The deployment's version and features."""
+        h = self._call("GET", "/v1/health")
+        return Health(ok=h["ok"], version=h["version"], preview_zone=h.get("previewZone"), backups=bool(h.get("backups")))
+
+    def list(self) -> List["Sandbox"]:
+        """All sandboxes, newest first."""
+        return [Sandbox(self, info) for info in self._call("GET", "/v1/sandboxes")]
+
+    def get(self, ref: str) -> "Sandbox":
+        """A sandbox by id (cx-xxxxxx) or name."""
+        return Sandbox(self, self._call("GET", _sandbox_path(ref)))
+
+    def create(
+        self,
+        name: Optional[str] = None,
+        size: Optional[str] = None,
+        idle_minutes: Optional[int] = None,
+        env: Optional[Dict[str, str]] = None,
+        files: Optional[Dict[str, str]] = None,
+        repo: Union[str, Dict[str, str], None] = None,
+    ) -> "Sandbox":
+        """Creates a sandbox and returns once it's running, usually in about 10 seconds.
+
+        size is standard-1 to standard-4 (default standard-2). idle_minutes
+        (default 30) is how long without activity before it saves and stops;
+        0 waits for the 6-hour platform limit. env and files (paths in the home
+        directory, such as ~/.npmrc) are applied at every start; repo, an
+        https:// URL with #branch if wanted, or {"url", "dir", "branch"}, is
+        cloned into the home directory. A failed clone leaves a notice.
+        """
+        body = _drop_none(name=name, size=size, idleMinutes=idle_minutes, env=env, files=files, repo=repo)
+        return Sandbox(self, self._call("POST", "/v1/sandboxes", body))
+
+    def list_keys(self) -> List[ProviderKey]:
+        """The AI provider keys sandboxes use; the keys themselves are never returned."""
+        return [_provider_key(k) for k in self._call("GET", "/v1/keys")]
+
+    def set_key(self, provider: str, key: str) -> ProviderKey:
+        """Sets a provider's key ("anthropic" or "openai").
+
+        Sandboxes started from then on get a placeholder, and the real key is
+        added to their HTTPS calls to the provider on the way out, so it never
+        enters a sandbox, its saves, backups or forks. A changed key reaches
+        running sandboxes within a minute.
+        """
+        return _provider_key(self._call("PUT", "/v1/keys/" + urllib.parse.quote(provider, safe=""), {"key": key}))
+
+    def delete_key(self, provider: str) -> None:
+        self._call("DELETE", "/v1/keys/" + urllib.parse.quote(provider, safe=""))
+
+    def _call(self, method: str, path: str, body: Optional[Dict[str, Any]] = None) -> Any:
+        data = None if body is None else json.dumps(body).encode()
+        req = urllib.request.Request(self.api_url + path, data=data, method=method)
+        req.add_header("Authorization", f"Bearer {self._key}")
+        req.add_header("User-Agent", f"cloudex-python/{__version__}")
+        if data is not None:
+            req.add_header("Content-Type", "application/json")
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as res:
+                text = res.read().decode()
+        except urllib.error.HTTPError as e:
+            text = e.read().decode(errors="replace")
+            try:
+                message = json.loads(text)["error"]
+            except (ValueError, KeyError, TypeError):
+                message = text.strip() or e.reason
+            raise CloudexError(e.code, str(message)) from None
+        except urllib.error.URLError as e:
+            raise CloudexError(0, f"can't reach {self.api_url}: {e.reason}") from None
+        return json.loads(text) if text else None
+
+
+def _provider_key(k: Dict[str, Any]) -> ProviderKey:
+    return ProviderKey(provider=k["provider"], hint=k["hint"], updated_at=k["updatedAt"])
+
+
+def _settings(s: Dict[str, Any]) -> Settings:
+    return Settings(env=s["env"], files=s["files"], repo=s.get("repo"))
+
+
+def _sandbox_path(ref: str) -> str:
+    return "/v1/sandboxes/" + urllib.parse.quote(ref, safe="")
+
+
+class Sandbox:
+    """A sandbox. Its fields are as of the last call that returned it; refresh() updates them.
+
+    info holds everything the API reports (camelCase keys, times in
+    milliseconds since the epoch); id, name and state are the common ones.
+    """
+
+    def __init__(self, client: Cloudex, info: Dict[str, Any]):
+        self._client = client
+        self.info = info
+
+    @property
+    def id(self) -> str:
+        return self.info["id"]
+
+    @property
+    def name(self) -> Optional[str]:
+        return self.info.get("name")
+
+    @property
+    def state(self) -> str:
+        return self.info["state"]
+
+    @property
+    def forked_from(self) -> Optional[str]:
+        return self.info.get("forkedFrom")
+
+    @property
+    def provider_keys(self) -> List[str]:
+        """Providers whose keys this run uses without holding them (see Cloudex.set_key)."""
+        return self.info.get("providerKeys") or []
+
+    def __repr__(self) -> str:
+        label = f" {self.name!r}" if self.name else ""
+        return f"<Sandbox {self.id}{label} {self.state}>"
+
+    def _path(self, suffix: str = "") -> str:
+        return _sandbox_path(self.id) + suffix
+
+    def _update(self, method: str, suffix: str, body: Optional[Dict[str, Any]] = None) -> "Sandbox":
+        self.info = self._client._call(method, self._path(suffix), body)
+        return self
+
+    def refresh(self) -> "Sandbox":
+        return self._update("GET", "")
+
+    def stop(self) -> "Sandbox":
+        """Saves the disk, backs up /home and stops."""
+        return self._update("POST", "/stop")
+
+    def resume(self, from_backup: bool = False) -> "Sandbox":
+        """Starts from the save, or with from_backup, from a fresh image with /home restored."""
+        return self._update("POST", "/resume", {"fromBackup": True} if from_backup else None)
+
+    def delete(self) -> None:
+        """Deletes the sandbox and its backups."""
+        self._client._call("DELETE", self._path())
+
+    def exec(
+        self,
+        command: Union[str, Sequence[str]],
+        root: bool = False,
+        cwd: Optional[str] = None,
+        timeout_sec: Optional[int] = None,
+    ) -> ExecResult:
+        """Runs a command with `bash -lc` and waits for it (default limit 600 s, at most 3600).
+
+        A string is run as shell code; a list is quoted, one argument per
+        element. A failing command doesn't raise: check exit_code.
+        """
+        cmd = command if isinstance(command, str) else shlex.join(command)
+        body = _drop_none(cmd=cmd, root=root or None, cwd=cwd, timeoutSec=timeout_sec)
+        r = self._client._call("POST", self._path("/exec"), body)
+        return ExecResult(exit_code=r["exitCode"], stdout=r["stdout"], stderr=r["stderr"], timed_out=r["timedOut"], ms=r["ms"])
+
+    def fork(
+        self,
+        count: int = 1,
+        name: Optional[str] = None,
+        size: Optional[str] = None,
+        idle_minutes: Optional[int] = None,
+    ) -> List["Sandbox"]:
+        """Makes sandboxes (1 to 10) that start from a copy of this one's whole disk.
+
+        A running sandbox is saved first, in seconds, and keeps running. With
+        count above 1, name is the start of <name>-1, <name>-2 and so on.
+        Size and idle minutes default to this sandbox's. Forks that failed to
+        start come back in state "error"; resume() tries again.
+        """
+        body = _drop_none(name=name, count=count, size=size, idleMinutes=idle_minutes)
+        return [Sandbox(self._client, info) for info in self._client._call("POST", self._path("/fork"), body)]
+
+    def host(self, port: int) -> str:
+        """An HTTPS link to a port, on the deployment's preview domain. Anyone with it can use it."""
+        return self._client._call("POST", self._path("/hosts"), {"port": port})["url"]
+
+    def desktop(self, size: Optional[str] = None) -> Desktop:
+        """Starts the desktop (Chrome and a terminal), or resizes a running one, and links to its viewer.
+
+        The first start installs it, which takes a minute or two.
+        """
+        d = self._client._call("POST", self._path("/desktop"), _drop_none(size=size))
+        return Desktop(
+            url=f"{self.host(d['port'])}/{d['path']}",
+            port=d["port"],
+            path=d["path"],
+            size=d["size"],
+            installed=d["installed"],
+            started=d["started"],
+        )
+
+    def stop_desktop(self) -> None:
+        self._client._call("DELETE", self._path("/desktop"))
+
+    def settings(self) -> Settings:
+        """The sandbox's environment variable names, files and repo."""
+        return _settings(self._client._call("GET", self._path("/settings")))
+
+    def update_settings(
+        self, env: Optional[Dict[str, Optional[str]]] = None, files: Optional[Dict[str, Optional[str]]] = None
+    ) -> Settings:
+        """Sets, or with None removes, environment variables and files.
+
+        A running sandbox gets the change at once, in new shells; a stopped one
+        when it next starts.
+        """
+        return _settings(self._client._call("PATCH", self._path("/settings"), _drop_none(env=env, files=files)))
+
+    def prompt(
+        self,
+        prompt: str,
+        agent: Optional[str] = None,
+        cwd: Optional[str] = None,
+        model: Optional[str] = None,
+    ) -> "Agent":
+        """Starts Claude Code (or agent="codex") on a task, with no terminal, and returns at once.
+
+        Follow it with events() or wait(), and continue the conversation with
+        send(). cwd defaults to the home directory, model to the agent's own.
+        With provider keys set, it needs no sign-in.
+        """
+        info = self._client._call("POST", self._path("/agents"), _drop_none(prompt=prompt, agent=agent, cwd=cwd, model=model))
+        return Agent(self._client, self._path("/agents/" + info["id"]), info)
+
+    def agents(self) -> List["Agent"]:
+        """The agents started in this sandbox, newest first."""
+        return [Agent(self._client, self._path("/agents/" + i["id"]), i) for i in self._client._call("GET", self._path("/agents"))]
+
+    def agent(self, id: str) -> "Agent":
+        """An agent by id (ag-xxxxxxxx)."""
+        path = self._path("/agents/" + urllib.parse.quote(id, safe=""))
+        return Agent(self._client, path, self._client._call("GET", path))
+
+
+class Agent:
+    """Claude Code or Codex working on a task in a sandbox.
+
+    Its fields are as of the last call that returned it; refresh(), events()
+    and wait() update them. info holds everything the API reports.
+    """
+
+    def __init__(self, client: Cloudex, path: str, info: Dict[str, Any]):
+        self._client = client
+        self._path = path
+        self.info = info
+
+    @property
+    def id(self) -> str:
+        return self.info["id"]
+
+    @property
+    def state(self) -> str:
+        """running while a turn is in progress or messages are queued, idle otherwise."""
+        return self.info["state"]
+
+    @property
+    def last_message(self) -> Optional[str]:
+        """The agent's final message in the last finished turn."""
+        return self.info.get("lastMessage")
+
+    @property
+    def error(self) -> Optional[str]:
+        """Why the last turn failed."""
+        return self.info.get("error")
+
+    def __repr__(self) -> str:
+        return f"<Agent {self.id} {self.info.get('agent')} {self.state}>"
+
+    def refresh(self) -> "Agent":
+        self.info = self._client._call("GET", self._path)
+        return self
+
+    def send(self, prompt: str, interrupt: bool = False) -> "Agent":
+        """Continues the conversation.
+
+        While a turn runs the message waits for it; with interrupt, the running
+        turn stops and queued messages are dropped first.
+        """
+        body = {"prompt": prompt, "interrupt": True} if interrupt else {"prompt": prompt}
+        self.info = self._client._call("POST", self._path + "/messages", body)
+        return self
+
+    def interrupt(self) -> "Agent":
+        """Stops the running turn and drops queued messages."""
+        self.info = self._client._call("POST", self._path + "/interrupt")
+        return self
+
+    def events(self, after: int = 0, follow: bool = True) -> Iterator[Dict[str, Any]]:
+        """The agent's events (dicts) from after (default 0, the start).
+
+        With follow (the default), waits for new ones until the agent is idle;
+        without, stops at the newest. Each request waits up to 25 seconds, so a
+        client timeout must be longer than that.
+        """
+        wait = 25 if follow else 0
+        while True:
+            page = self._client._call("GET", f"{self._path}/events?after={after}&wait={wait}")
+            self.info = page["agent"]
+            yield from page["events"]
+            after = page["next"]
+            if after >= self.info["events"] and (not follow or self.info["state"] == "idle"):
+                return
+
+    def wait(self) -> "Agent":
+        """Waits until the agent is idle; then last_message and error tell how its last turn went."""
+        for _ in self.events(after=self.info["events"]):
+            pass
+        return self

cloudex-0.1.11/tests/test_cloudex.py

@@ -0,0 +1,212 @@
+import json
+import os
+import tempfile
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from unittest import mock
+
+from cloudex import Cloudex, CloudexError, ExecResult, ProviderKey, Settings
+
+
+def info(id, **extra):
+    base = {
+        "id": id, "name": None, "size": "standard-2", "state": "running", "idleMinutes": 30,
+        "createdAt": 1, "updatedAt": 1, "startedAt": 1, "stoppedAt": None,
+        "savedAt": None, "savedBytes": None, "error": None,
+    }
+    base.update(extra)
+    return base
+
+
+class FakeAPI(BaseHTTPRequestHandler):
+    """Answers by "METHOD /path" from routes and records what it was sent."""
+
+    routes = {}
+    seen = []
+
+    def _handle(self):
+        length = int(self.headers.get("Content-Length") or 0)
+        body = json.loads(self.rfile.read(length)) if length else None
+        route = f"{self.command} {self.path}"
+        FakeAPI.seen.append({"route": route, "auth": self.headers.get("Authorization"), "body": body})
+        status, answer = FakeAPI.routes.get(route, (404, {"error": f"no route {route}"}))
+        data = json.dumps(answer).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(data)))
+        self.end_headers()
+        self.wfile.write(data)
+
+    do_GET = do_POST = do_PUT = do_PATCH = do_DELETE = _handle
+
+    def log_message(self, *args):
+        pass
+
+
+class CloudexTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.server = ThreadingHTTPServer(("127.0.0.1", 0), FakeAPI)
+        threading.Thread(target=cls.server.serve_forever, daemon=True).start()
+        cls.url = f"http://127.0.0.1:{cls.server.server_address[1]}"
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.server.shutdown()
+
+    def setUp(self):
+        FakeAPI.routes = {}
+        FakeAPI.seen = []
+        env = {k: v for k, v in os.environ.items() if not k.startswith("CLOUDEX_")}
+        patcher = mock.patch.dict(os.environ, env, clear=True)
+        patcher.start()
+        self.addCleanup(patcher.stop)
+        self.cx = Cloudex(self.url + "/", "k1")
+
+    def test_create_sends_options_with_the_key(self):
+        FakeAPI.routes["POST /v1/sandboxes"] = (201, info("cx-aaa111", name="web"))
+        box = self.cx.create(name="web", idle_minutes=5)
+        self.assertEqual((box.id, box.name, box.state), ("cx-aaa111", "web", "running"))
+        self.assertEqual(
+            FakeAPI.seen, [{"route": "POST /v1/sandboxes", "auth": "Bearer k1", "body": {"name": "web", "idleMinutes": 5}}]
+        )
+
+    def test_api_errors_raise_with_status_and_message(self):
+        FakeAPI.routes["GET /v1/sandboxes/nope"] = (404, {"error": "no sandbox named nope"})
+        with self.assertRaises(CloudexError) as caught:
+            self.cx.get("nope")
+        self.assertEqual((caught.exception.status, str(caught.exception)), (404, "no sandbox named nope"))
+
+    def test_lifecycle_updates_the_fields(self):
+        FakeAPI.routes["GET /v1/sandboxes/my%20box"] = (200, info("cx-aaa111", name="my box"))
+        FakeAPI.routes["POST /v1/sandboxes/cx-aaa111/stop"] = (200, info("cx-aaa111", state="stopped", savedAt=9))
+        FakeAPI.routes["POST /v1/sandboxes/cx-aaa111/resume"] = (200, info("cx-aaa111", notice="restored"))
+        FakeAPI.routes["DELETE /v1/sandboxes/cx-aaa111"] = (200, {"deleted": "cx-aaa111"})
+        box = self.cx.get("my box")
+        self.assertEqual(box.stop().state, "stopped")
+        self.assertEqual(box.info["savedAt"], 9)
+        box.resume(from_backup=True)
+        self.assertEqual(box.info["notice"], "restored")
+        box.delete()
+        self.assertEqual(FakeAPI.seen[-2]["body"], {"fromBackup": True})
+        self.assertEqual(FakeAPI.seen[-1]["route"], "DELETE /v1/sandboxes/cx-aaa111")
+
+    def test_exec_quotes_a_list(self):
+        FakeAPI.routes["GET /v1/sandboxes/web"] = (200, info("cx-aaa111"))
+        FakeAPI.routes["POST /v1/sandboxes/cx-aaa111/exec"] = (
+            200, {"exitCode": 1, "stdout": "", "stderr": "no", "timedOut": False, "ms": 3},
+        )
+        box = self.cx.get("web")
+        result = box.exec(["echo", "it's", "a b"], root=True, timeout_sec=5)
+        self.assertEqual(result, ExecResult(exit_code=1, stdout="", stderr="no", timed_out=False, ms=3))
+        self.assertEqual(FakeAPI.seen[-1]["body"], {"cmd": "echo 'it'\"'\"'s' 'a b'", "root": True, "timeoutSec": 5})
+        box.exec("ls | wc -l")
+        self.assertEqual(FakeAPI.seen[-1]["body"], {"cmd": "ls | wc -l"})
+
+    def test_fork_returns_working_sandboxes(self):
+        FakeAPI.routes["GET /v1/sandboxes/web"] = (200, info("cx-aaa111"))
+        FakeAPI.routes["POST /v1/sandboxes/cx-aaa111/fork"] = (201, [
+            info("cx-fff111", name="a-1", forkedFrom="cx-aaa111"),
+            info("cx-fff222", name="a-2", state="error", error="no room"),
+        ])
+        FakeAPI.routes["POST /v1/sandboxes/cx-fff111/stop"] = (200, info("cx-fff111", state="stopped"))
+        forks = self.cx.get("web").fork(count=2, name="a")
+        self.assertEqual(FakeAPI.seen[-1]["body"], {"name": "a", "count": 2})
+        self.assertEqual([(f.name, f.state, f.forked_from) for f in forks], [("a-1", "running", "cx-aaa111"), ("a-2", "error", None)])
+        self.assertEqual(forks[0].stop().state, "stopped")
+
+    def test_desktop_links_to_the_viewer(self):
+        FakeAPI.routes["GET /v1/sandboxes/web"] = (200, info("cx-aaa111"))
+        FakeAPI.routes["POST /v1/sandboxes/cx-aaa111/desktop"] = (
+            200, {"port": 6080, "path": "vnc.html?autoconnect=1", "size": "1280x720", "installed": False, "started": True},
+        )
+        FakeAPI.routes["POST /v1/sandboxes/cx-aaa111/hosts"] = (200, {"url": "https://6080-cx-aaa111-tok.example.com"})
+        d = self.cx.get("web").desktop()
+        self.assertEqual(d.url, "https://6080-cx-aaa111-tok.example.com/vnc.html?autoconnect=1")
+        self.assertEqual(FakeAPI.seen[-2]["body"], {})
+
+    def test_environment_then_saved_deployment(self):
+        FakeAPI.routes["GET /v1/health"] = (200, {"ok": True, "version": "v0", "previewZone": None})
+        os.environ["CLOUDEX_API_URL"] = self.url
+        os.environ["CLOUDEX_API_KEY"] = "from-env"
+        Cloudex().health()
+        self.assertEqual(FakeAPI.seen[-1]["auth"], "Bearer from-env")
+        del os.environ["CLOUDEX_API_URL"], os.environ["CLOUDEX_API_KEY"]
+        with tempfile.TemporaryDirectory() as d:
+            with open(os.path.join(d, "config.json"), "w") as f:
+                json.dump({"apiUrl": self.url, "apiKey": "from-config"}, f)
+            os.environ["CLOUDEX_CONFIG_DIR"] = d
+            self.assertEqual(Cloudex().health().version, "v0")
+        self.assertEqual(FakeAPI.seen[-1]["auth"], "Bearer from-config")
+
+    def test_no_deployment_is_a_clear_error(self):
+        with tempfile.TemporaryDirectory() as d:
+            os.environ["CLOUDEX_CONFIG_DIR"] = d
+            with self.assertRaises(CloudexError) as caught:
+                Cloudex()
+        self.assertEqual(caught.exception.status, 0)
+        self.assertIn("cloudex login", str(caught.exception))
+
+    def test_provider_keys(self):
+        FakeAPI.routes["PUT /v1/keys/anthropic"] = (200, {"provider": "anthropic", "hint": "…wxyz", "updatedAt": 5})
+        FakeAPI.routes["GET /v1/keys"] = (200, [{"provider": "anthropic", "hint": "…wxyz", "updatedAt": 5}])
+        FakeAPI.routes["DELETE /v1/keys/anthropic"] = (200, {"deleted": "anthropic"})
+        FakeAPI.routes["GET /v1/sandboxes/web"] = (200, info("cx-aaa111", providerKeys=["anthropic"]))
+        self.assertEqual(self.cx.set_key("anthropic", "sk-ant-x-wxyz"), ProviderKey("anthropic", "…wxyz", 5))
+        self.assertEqual(FakeAPI.seen[-1]["body"], {"key": "sk-ant-x-wxyz"})
+        self.assertEqual([k.provider for k in self.cx.list_keys()], ["anthropic"])
+        self.assertEqual(self.cx.get("web").provider_keys, ["anthropic"])
+        self.cx.delete_key("anthropic")
+        self.assertEqual(FakeAPI.seen[-1]["route"], "DELETE /v1/keys/anthropic")
+
+    def test_agents(self):
+        def agent(**extra):
+            base = {"id": "ag-aaaa1111", "agent": "claude", "state": "running", "cwd": "/home/cloudex", "model": None,
+                    "turns": 1, "queued": 0, "events": 1, "sessionId": None, "lastMessage": None,
+                    "lastExitCode": None, "error": None, "createdAt": 1, "updatedAt": 1}
+            base.update(extra)
+            return base
+
+        path = "/v1/sandboxes/cx-aaa111/agents/ag-aaaa1111"
+        FakeAPI.routes["GET /v1/sandboxes/web"] = (200, info("cx-aaa111"))
+        FakeAPI.routes["POST /v1/sandboxes/cx-aaa111/agents"] = (201, agent(turns=0, events=0))
+        FakeAPI.routes[f"GET {path}/events?after=0&wait=25"] = (200, {
+            "events": [{"seq": 1, "turn": 1, "at": 1, "type": "prompt", "text": "fix it"}],
+            "next": 1, "agent": agent(events=2)})
+        FakeAPI.routes[f"GET {path}/events?after=1&wait=25"] = (200, {
+            "events": [{"seq": 2, "turn": 1, "at": 2, "type": "end", "exitCode": 0}],
+            "next": 2, "agent": agent(state="idle", events=2, lastMessage="fixed")})
+        FakeAPI.routes[f"GET {path}/events?after=2&wait=25"] = (200, {"events": [], "next": 2, "agent": agent(state="idle", events=2, lastMessage="fixed")})
+        FakeAPI.routes[f"POST {path}/messages"] = (200, agent(queued=1))
+        FakeAPI.routes[f"POST {path}/interrupt"] = (200, agent(state="idle", error="interrupted"))
+
+        a = self.cx.get("web").prompt("fix it", agent="codex")
+        self.assertEqual(FakeAPI.seen[-1]["body"], {"prompt": "fix it", "agent": "codex"})
+        self.assertEqual([e["type"] for e in a.events()], ["prompt", "end"])
+        self.assertEqual((a.state, a.last_message), ("idle", "fixed"))
+        self.assertIs(a.wait(), a)
+        self.assertEqual(FakeAPI.seen[-1]["route"], f"GET {path}/events?after=2&wait=25")
+        a.send("and the docs", interrupt=True)
+        self.assertEqual(FakeAPI.seen[-1]["body"], {"prompt": "and the docs", "interrupt": True})
+        self.assertEqual(a.interrupt().error, "interrupted")
+
+    def test_settings(self):
+        view = {"env": ["A"], "files": ["~/.npmrc"], "repo": None}
+        FakeAPI.routes["POST /v1/sandboxes"] = (201, info("cx-aaa111"))
+        FakeAPI.routes["GET /v1/sandboxes/cx-aaa111/settings"] = (200, view)
+        FakeAPI.routes["PATCH /v1/sandboxes/cx-aaa111/settings"] = (200, dict(view, env=[]))
+        box = self.cx.create(env={"A": "1"}, files={"~/.npmrc": "x"}, repo="https://github.com/you/app#dev")
+        self.assertEqual(FakeAPI.seen[-1]["body"], {"env": {"A": "1"}, "files": {"~/.npmrc": "x"}, "repo": "https://github.com/you/app#dev"})
+        self.assertEqual(box.settings(), Settings(env=["A"], files=["~/.npmrc"], repo=None))
+        self.assertEqual(box.update_settings(env={"A": None}).env, [])
+        self.assertEqual(FakeAPI.seen[-1]["body"], {"env": {"A": None}})
+
+    def test_unreachable_api(self):
+        with self.assertRaises(CloudexError) as caught:
+            Cloudex("http://127.0.0.1:9", "k").list()
+        self.assertEqual(caught.exception.status, 0)
+
+
+if __name__ == "__main__":
+    unittest.main()