flaxcloud 0.5.0__tar.gz → 0.5.2__tar.gz

{flaxcloud-0.5.0 → flaxcloud-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flaxcloud
-Version: 0.5.0
+Version: 0.5.2
 Summary: Python SDK and CLI for Flax Cloud: isolated cloud sandboxes.
 Project-URL: Homepage, https://flaxcloud.com
 Project-URL: Documentation, https://github.com/tomitokko/flax-cloud/blob/main/docs/user/sdk.md
@@ -65,19 +65,25 @@ CLI (which stores it in `~/.config/flax/config.json`):
 
 ```bash
 export FLAX_API_KEY=flax_live_...
+# Optional, for local/self-hosted targets:
+export FLAX_BASE_URL=https://flaxcloud.com
 # or
 flax login
 ```
 
+Credentials resolve in this order: explicit `api_key`, CLI `--key`, `FLAX_API_KEY`, then
+`~/.config/flax/config.json`. The base URL is `base_url`, CLI `--url`, `FLAX_BASE_URL`, then
+`https://flaxcloud.com`.
+
 ## SDK
 
 ```python
 from flaxcloud import FlaxClient
 
-flax = FlaxClient()  # reads FLAX_API_KEY
+flax = FlaxClient()  # reads FLAX_API_KEY and optional FLAX_BASE_URL
 
 # create_sandbox returns a handle with methods; use it as a context manager to auto-destroy
-with flax.create_sandbox(template="python", name="ci-run") as sb:
+with flax.create_sandbox(template="python", name="ci-run", memory_mb=512) as sb:
     print(sb.name, sb.id)
     out = sb.run("python3 -c 'print(6*7)'")
     print(out.stdout)          # "42\n"
@@ -91,6 +97,22 @@ with flax.create_sandbox(template="python", name="ci-run") as sb:
     print(sb.create_preview_link(8000).url)
 ```
 
+Per-sandbox memory is plan-limited: Free `1 GB`, Pro `2 GB`, Builder `4 GB`, Team `8 GB`.
+Requesting more than your plan allows raises `FlaxQuotaError` with `code == "memory_limit"`:
+
+```python
+from flaxcloud import FlaxClient, FlaxQuotaError
+
+flax = FlaxClient()
+try:
+    flax.create_sandbox(template="python", memory_mb=2048)
+except FlaxQuotaError as exc:
+    if exc.code == "memory_limit":
+        print("Choose a smaller sandbox or upgrade your plan.")
+    else:
+        raise
+```
+
 Background commands:
 
 ```python
@@ -105,11 +127,15 @@ Environment variables, code execution, git, and filesystem helpers:
 ```python
 sb = flax.create_sandbox(template="python", env={"API_BASE": "https://example.com"})
 sb.run("printenv TOKEN", env={"TOKEN": "secret"})        # per-command override
+sb.set_env({"API_BASE": "https://new.example.com"})       # future process defaults
 sb.code_run("print(6*7)", language="python")             # also node/bash/ruby
 sb.git.clone("https://github.com/me/repo.git", "/workspace/repo")
 sb.mkdir("/workspace/out"); sb.find("/workspace", name="*.py")
 ```
 
+Environment payloads are encrypted at rest. Flax also places `HOME` and XDG state under the
+durable workspace automatically, so normal tool state survives stop/resume.
+
 Stateful sessions - working directory and exported env persist across commands:
 
 ```python
@@ -245,6 +271,9 @@ flax session create sbx_abc123                     # cwd/env persist across exec
 flax session exec ses_xyz "cd src && export E=1"
 flax cp ./app.py sbx_abc123:/workspace/app.py
 flax ls sbx_abc123 /workspace
+flax snapshot create sbx_abc123 agent-base
+flax snapshot ls
+flax snapshot rm snap_abc123
 flax preview sbx_abc123 8000
 flax sandbox rm sbx_abc123
 ```

{flaxcloud-0.5.0 → flaxcloud-0.5.2}/README.md

@@ -16,19 +16,25 @@ CLI (which stores it in `~/.config/flax/config.json`):
 
 ```bash
 export FLAX_API_KEY=flax_live_...
+# Optional, for local/self-hosted targets:
+export FLAX_BASE_URL=https://flaxcloud.com
 # or
 flax login
 ```
 
+Credentials resolve in this order: explicit `api_key`, CLI `--key`, `FLAX_API_KEY`, then
+`~/.config/flax/config.json`. The base URL is `base_url`, CLI `--url`, `FLAX_BASE_URL`, then
+`https://flaxcloud.com`.
+
 ## SDK
 
 ```python
 from flaxcloud import FlaxClient
 
-flax = FlaxClient()  # reads FLAX_API_KEY
+flax = FlaxClient()  # reads FLAX_API_KEY and optional FLAX_BASE_URL
 
 # create_sandbox returns a handle with methods; use it as a context manager to auto-destroy
-with flax.create_sandbox(template="python", name="ci-run") as sb:
+with flax.create_sandbox(template="python", name="ci-run", memory_mb=512) as sb:
     print(sb.name, sb.id)
     out = sb.run("python3 -c 'print(6*7)'")
     print(out.stdout)          # "42\n"
@@ -42,6 +48,22 @@ with flax.create_sandbox(template="python", name="ci-run") as sb:
     print(sb.create_preview_link(8000).url)
 ```
 
+Per-sandbox memory is plan-limited: Free `1 GB`, Pro `2 GB`, Builder `4 GB`, Team `8 GB`.
+Requesting more than your plan allows raises `FlaxQuotaError` with `code == "memory_limit"`:
+
+```python
+from flaxcloud import FlaxClient, FlaxQuotaError
+
+flax = FlaxClient()
+try:
+    flax.create_sandbox(template="python", memory_mb=2048)
+except FlaxQuotaError as exc:
+    if exc.code == "memory_limit":
+        print("Choose a smaller sandbox or upgrade your plan.")
+    else:
+        raise
+```
+
 Background commands:
 
 ```python
@@ -56,11 +78,15 @@ Environment variables, code execution, git, and filesystem helpers:
 ```python
 sb = flax.create_sandbox(template="python", env={"API_BASE": "https://example.com"})
 sb.run("printenv TOKEN", env={"TOKEN": "secret"})        # per-command override
+sb.set_env({"API_BASE": "https://new.example.com"})       # future process defaults
 sb.code_run("print(6*7)", language="python")             # also node/bash/ruby
 sb.git.clone("https://github.com/me/repo.git", "/workspace/repo")
 sb.mkdir("/workspace/out"); sb.find("/workspace", name="*.py")
 ```
 
+Environment payloads are encrypted at rest. Flax also places `HOME` and XDG state under the
+durable workspace automatically, so normal tool state survives stop/resume.
+
 Stateful sessions - working directory and exported env persist across commands:
 
 ```python
@@ -196,6 +222,9 @@ flax session create sbx_abc123                     # cwd/env persist across exec
 flax session exec ses_xyz "cd src && export E=1"
 flax cp ./app.py sbx_abc123:/workspace/app.py
 flax ls sbx_abc123 /workspace
+flax snapshot create sbx_abc123 agent-base
+flax snapshot ls
+flax snapshot rm snap_abc123
 flax preview sbx_abc123 8000
 flax sandbox rm sbx_abc123
 ```

{flaxcloud-0.5.0 → flaxcloud-0.5.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "flaxcloud"
-version = "0.5.0"
+version = "0.5.2"
 description = "Python SDK and CLI for Flax Cloud: isolated cloud sandboxes."
 readme = "README.md"
 requires-python = ">=3.9"

{flaxcloud-0.5.0 → flaxcloud-0.5.2}/src/flaxcloud/__init__.py

@@ -23,15 +23,30 @@ from .errors import (
     FlaxQuotaError,
     FlaxServerError,
 )
-from .models import Command, FileEntry, PreviewLink, SessionResult, Snapshot, StartupStatus, Template
-from .sandbox import Sandbox, SandboxBrowser, Session
+from .models import (
+    Command,
+    FileEntry,
+    PreviewLink,
+    SessionResult,
+    Snapshot,
+    StartupStatus,
+    Template,
+)
+from .sandbox import CommandStream, Sandbox, SandboxBrowser, SandboxGit, Session
 
-__version__ = "0.5.0"
+__version__ = "0.5.2"
 
 
 def __getattr__(name: str):
     # Lazily expose the async client so importing the package doesn't require asyncio setup.
-    if name in ("AsyncFlaxClient", "AsyncSandbox", "AsyncSandboxBrowser"):
+    if name in (
+        "AsyncFlaxClient",
+        "AsyncSandbox",
+        "AsyncSandboxBrowser",
+        "AsyncSandboxGit",
+        "AsyncCommandStream",
+        "AsyncSession",
+    ):
         from . import aio
 
         return getattr(aio, name)
@@ -43,11 +58,16 @@ __all__ = [
     "FlaxImage",
     "Sandbox",
     "SandboxBrowser",
+    "SandboxGit",
+    "CommandStream",
     "Session",
     "SessionResult",
     "AsyncFlaxClient",
     "AsyncSandbox",
     "AsyncSandboxBrowser",
+    "AsyncSandboxGit",
+    "AsyncCommandStream",
+    "AsyncSession",
     "Command",
     "FileEntry",
     "PreviewLink",

{flaxcloud-0.5.0 → flaxcloud-0.5.2}/src/flaxcloud/aio.py

@@ -24,6 +24,7 @@ import base64
 import os
 import random
 import shlex
+from pathlib import Path
 from typing import TYPE_CHECKING, Any, Optional, Union
 
 import httpx
@@ -38,7 +39,15 @@ from .client import (
     _user_agent,
 )
 from .errors import FlaxAuthError, FlaxConnectionError, FlaxError, error_from_response
-from .models import Command, FileEntry, PreviewLink, SessionResult, Snapshot, StartupStatus, Template
+from .models import (
+    Command,
+    FileEntry,
+    PreviewLink,
+    SessionResult,
+    Snapshot,
+    StartupStatus,
+    Template,
+)
 from .sandbox import WORKSPACE
 
 
@@ -296,6 +305,17 @@ class AsyncFlaxClient:
     async def usage(self) -> dict:
         return await self.request("GET", "/v1/usage")
 
+    # ------------------------------- API keys --------------------------------
+    async def list_api_keys(self) -> list[dict]:
+        data = await self.request("GET", "/v1/keys")
+        return data.get("data", []) if isinstance(data, dict) else data
+
+    async def create_api_key(self, name: str = "default") -> dict:
+        return await self.request("POST", "/v1/keys", json={"name": name})
+
+    async def delete_api_key(self, key_id: str) -> None:
+        await self.request("DELETE", f"/v1/keys/{key_id}")
+
     # ------------------------------- lifecycle -------------------------------
     async def aclose(self) -> None:
         if self._owns_client:
@@ -317,14 +337,30 @@ class AsyncSandbox:
     def id(self) -> str:
         return self._data["id"]
 
+    @property
+    def name(self) -> Optional[str]:
+        return self._data.get("name")
+
     @property
     def status(self) -> str:
         return self._data.get("status", "")
 
+    @property
+    def template(self) -> str:
+        return self._data.get("template", "")
+
+    @property
+    def network_mode(self) -> str:
+        return self._data.get("network_mode", "bridge")
+
     @property
     def env(self) -> dict:
         return dict(self._data.get("env") or {})
 
+    @property
+    def startup_command(self) -> Optional[str]:
+        return self._data.get("startup_command")
+
     @property
     def capabilities(self) -> list[str]:
         return list(self._data.get("capabilities") or [])
@@ -334,6 +370,14 @@ class AsyncSandbox:
         model = self._data.get("model")
         return dict(model) if isinstance(model, dict) else None
 
+    @property
+    def data(self) -> dict:
+        return dict(self._data)
+
+    @property
+    def git(self) -> "AsyncSandboxGit":
+        return AsyncSandboxGit(self)
+
     @property
     def browser(self) -> "AsyncSandboxBrowser":
         """CDP-first browser helpers for browser-capable sandboxes."""
@@ -346,6 +390,13 @@ class AsyncSandbox:
         self._data = await self._client.request("GET", f"/v1/sandboxes/{self.id}")
         return self
 
+    async def set_env(self, env: dict[str, str]) -> "AsyncSandbox":
+        """Replace defaults used by future commands, terminals, and startup launches."""
+        self._data = await self._client.request(
+            "PUT", f"/v1/sandboxes/{self.id}/env", json={"env": env}
+        )
+        return self
+
     async def stop(self) -> "AsyncSandbox":
         self._data = await self._client.request("POST", f"/v1/sandboxes/{self.id}/stop")
         return self
@@ -449,12 +500,21 @@ class AsyncSandbox:
             json={"path": path, "content_base64": base64.b64encode(raw).decode()},
         )
 
+    async def upload_file(self, local_path: str, remote_path: Optional[str] = None) -> None:
+        destination = remote_path or f"{WORKSPACE}/{os.path.basename(local_path)}"
+        content = await asyncio.to_thread(Path(local_path).read_bytes)
+        await self.upload(destination, content)
+
     async def download(self, path: str) -> bytes:
         data = await self._client.request(
             "GET", f"/v1/sandboxes/{self.id}/files", params={"path": path}
         )
         return base64.b64decode(data["content_base64"])
 
+    async def download_file(self, remote_path: str, local_path: str) -> None:
+        content = await self.download(remote_path)
+        await asyncio.to_thread(Path(local_path).write_bytes, content)
+
     async def list_files(self, path: str = WORKSPACE) -> list[FileEntry]:
         data = await self._client.request(
             "GET", f"/v1/sandboxes/{self.id}/files/list", params={"path": path}
@@ -478,6 +538,16 @@ class AsyncSandbox:
     async def exists(self, path: str) -> bool:
         return (await self.run(f"test -e {shlex.quote(path)}")).exit_code == 0
 
+    async def find(
+        self, path: str = WORKSPACE, *, name: Optional[str] = None, max_results: int = 1000
+    ) -> list[str]:
+        cmd = f"find {shlex.quote(path)} -type f"
+        if name:
+            cmd += f" -name {shlex.quote(name)}"
+        cmd += f" 2>/dev/null | head -n {int(max_results)}"
+        out = await self.run(cmd)
+        return [line for line in out.stdout.splitlines() if line.strip()]
+
     # startup
     async def startup(self) -> StartupStatus:
         return StartupStatus.from_dict(
@@ -504,6 +574,17 @@ class AsyncSandbox:
             )
         )
 
+    async def get_preview_link(self) -> PreviewLink:
+        return PreviewLink.from_dict(
+            await self._client.request("GET", f"/v1/sandboxes/{self.id}/preview-link")
+        )
+
+    async def disable_preview_link(self) -> None:
+        await self._client.request("DELETE", f"/v1/sandboxes/{self.id}/preview-link")
+
+    def preview_url(self, port: int, path: str = "") -> str:
+        return f"{self._client.base_url}/v1/sandboxes/{self.id}/preview/{port}/{path.lstrip('/')}"
+
     # sessions
     async def create_session(self) -> "AsyncSession":
         data = await self._client.request("POST", f"/v1/sandboxes/{self.id}/sessions")
@@ -514,6 +595,59 @@ class AsyncSandbox:
         return [AsyncSession(self._client, d) for d in data.get("data", [])]
 
 
+class AsyncSandboxGit:
+    """Async git convenience operations run inside a sandbox."""
+
+    def __init__(self, sandbox: AsyncSandbox) -> None:
+        self._sb = sandbox
+
+    async def clone(
+        self, url: str, path: Optional[str] = None, *, timeout: int = 300
+    ) -> Command:
+        cmd = f"git clone {shlex.quote(url)}"
+        if path:
+            cmd += f" {shlex.quote(path)}"
+        return await self._sb.run(cmd, timeout=timeout)
+
+    async def status(self, path: str = WORKSPACE) -> Command:
+        return await self._sb.run(f"cd {shlex.quote(path)} && git status --short --branch")
+
+    async def branches(self, path: str = WORKSPACE) -> list[str]:
+        out = await self._sb.run(
+            f"cd {shlex.quote(path)} && git branch --format='%(refname:short)'"
+        )
+        return [line.strip() for line in out.stdout.splitlines() if line.strip()]
+
+    async def checkout(
+        self, ref: str, path: str = WORKSPACE, *, create: bool = False
+    ) -> Command:
+        flag = "-b " if create else ""
+        return await self._sb.run(
+            f"cd {shlex.quote(path)} && git checkout {flag}{shlex.quote(ref)}"
+        )
+
+    async def add(self, path: str = WORKSPACE, pathspec: str = ".") -> Command:
+        return await self._sb.run(
+            f"cd {shlex.quote(path)} && git add {shlex.quote(pathspec)}"
+        )
+
+    async def commit(self, message: str, path: str = WORKSPACE) -> Command:
+        return await self._sb.run(
+            f"cd {shlex.quote(path)} && git commit -m {shlex.quote(message)}"
+        )
+
+    async def push(
+        self, path: str = WORKSPACE, *, remote: str = "origin", branch: str = ""
+    ) -> Command:
+        target = f" {shlex.quote(remote)} {shlex.quote(branch)}" if branch else ""
+        return await self._sb.run(
+            f"cd {shlex.quote(path)} && git push{target}", timeout=300
+        )
+
+    async def pull(self, path: str = WORKSPACE, *, timeout: int = 300) -> Command:
+        return await self._sb.run(f"cd {shlex.quote(path)} && git pull", timeout=timeout)
+
+
 class AsyncSandboxBrowser:
     """Async CDP-first helpers for the canonical browser process inside a sandbox."""
 
@@ -589,6 +723,10 @@ class AsyncCommandStream:
         if error is not None:
             raise FlaxError(f"streamed command failed: {error}")
 
+    async def read(self) -> str:
+        """Consume the whole stream and return the joined output."""
+        return "".join([chunk async for chunk in self])
+
 
 class AsyncSession:
     """Async stateful session; cwd/exported env persist across `run()` calls."""
@@ -601,6 +739,10 @@ class AsyncSession:
     def id(self) -> str:
         return self._data["id"]
 
+    @property
+    def sandbox_id(self) -> str:
+        return self._data["sandbox_id"]
+
     @property
     def cwd(self) -> str:
         return self._data.get("cwd", WORKSPACE)

{flaxcloud-0.5.0 → flaxcloud-0.5.2}/src/flaxcloud/cli.py

@@ -325,6 +325,30 @@ def cmd_template(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_snapshot(args: argparse.Namespace) -> int:
+    client = _client(args)
+    if args.snapshot_cmd == "create":
+        snap = client.get_sandbox(args.sandbox_id).create_snapshot(args.name)
+        print(snap.id)
+        if not args.quiet:
+            print(f"name={snap.name} size={snap.size_bytes} template={snap.template}", file=sys.stderr)
+        return 0
+    if args.snapshot_cmd == "ls":
+        snapshots = client.list_snapshots()
+        if not snapshots:
+            print("No snapshots.")
+            return 0
+        rows = [[s.name, s.id, s.template, str(s.memory_mb), str(s.size_bytes)] for s in snapshots]
+        _print_rows(["NAME", "ID", "TEMPLATE", "MEMORY_MB", "SIZE_BYTES"], rows)
+        return 0
+    if args.snapshot_cmd == "rm":
+        for sid in args.ids:
+            client.delete_snapshot(sid)
+            print(f"deleted {sid}")
+        return 0
+    return 0
+
+
 def cmd_preview(args: argparse.Namespace) -> int:
     link = _client(args).get_sandbox(args.id).create_preview_link(args.port)
     if link.url:
@@ -434,6 +458,18 @@ def build_parser() -> argparse.ArgumentParser:
     trm.add_argument("id")
     trm.set_defaults(func=cmd_template)
 
+    sn = sub.add_parser("snapshot", help="manage filesystem snapshots")
+    sn_sub = sn.add_subparsers(dest="snapshot_cmd", required=True)
+    snc = sn_sub.add_parser("create", help="create a snapshot from a sandbox")
+    snc.add_argument("sandbox_id")
+    snc.add_argument("name", nargs="?", help="snapshot name")
+    snc.add_argument("-q", "--quiet", action="store_true", help="print only the snapshot id")
+    snc.set_defaults(func=cmd_snapshot)
+    sn_sub.add_parser("ls", help="list snapshots").set_defaults(func=cmd_snapshot)
+    snrm = sn_sub.add_parser("rm", help="delete snapshot(s)")
+    snrm.add_argument("ids", nargs="+")
+    snrm.set_defaults(func=cmd_snapshot)
+
     lg = sub.add_parser("logs", help="show a command's output/status")
     lg.add_argument("id")
     lg.add_argument("command_id")

flaxcloud-0.5.2/src/flaxcloud/py.typed

@@ -0,0 +1 @@
+

{flaxcloud-0.5.0 → flaxcloud-0.5.2}/src/flaxcloud/sandbox.py

@@ -84,6 +84,13 @@ class Sandbox:
         self._data = self._client.request("GET", f"/v1/sandboxes/{self.id}")
         return self
 
+    def set_env(self, env: dict[str, str]) -> "Sandbox":
+        """Replace defaults used by future commands, terminals, and startup launches."""
+        self._data = self._client.request(
+            "PUT", f"/v1/sandboxes/{self.id}/env", json={"env": env}
+        )
+        return self
+
     def stop(self) -> "Sandbox":
         self._data = self._client.request("POST", f"/v1/sandboxes/{self.id}/stop")
         return self