flaxcloud 0.3.0__tar.gz

flaxcloud-0.3.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Environment
+.env
+# Local secret overrides synced to the server (never committed)
+infra/secrets.env
+secrets.env
+
+# Local databases
+*.db
+*.sqlite
+*.sqlite3
+
+# Node
+node_modules/
+.next/
+dist/
+build/
+
+# OS / editor
+.DS_Store
+*.log

flaxcloud-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flax Cloud
+
+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.

flaxcloud-0.3.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: flaxcloud
+Version: 0.3.0
+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
+Project-URL: Source, https://github.com/tomitokko/flax-cloud
+Project-URL: Issues, https://github.com/tomitokko/flax-cloud/issues
+Author: Flax Cloud
+License: MIT License
+        
+        Copyright (c) 2026 Flax Cloud
+        
+        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.
+License-File: LICENSE
+Keywords: agents,cloud,code execution,flax,sandbox
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Description-Content-Type: text/markdown
+
+# flaxcloud — Python SDK & CLI for Flax Cloud
+
+Programmatic access to [Flax Cloud](https://flaxcloud.com) isolated sandboxes: create them,
+run commands, move files, preview servers, and wire them into agents/automation.
+
+## Install
+
+```bash
+pip install flaxcloud
+```
+
+## Authenticate
+
+Get an API key from the dashboard, then either set an environment variable or log in with the
+CLI (which stores it in `~/.config/flax/config.json`):
+
+```bash
+export FLAX_API_KEY=flax_live_...
+# or
+flax login
+```
+
+## SDK
+
+```python
+from flaxcloud import FlaxClient
+
+flax = FlaxClient()  # reads FLAX_API_KEY
+
+# create_sandbox returns a handle with methods; use it as a context manager to auto-destroy
+with flax.create_sandbox(template="python") as sb:
+    out = sb.run("python3 -c 'print(6*7)'")
+    print(out.stdout)          # "42\n"
+
+    sb.upload("/workspace/app.py", "print('hello')\n")
+    print(sb.run("python3 app.py").stdout)
+
+    # long-running server + a shareable preview link
+    sb.set_startup("python3 -m http.server 8000 --bind 0.0.0.0")
+    sb.run_startup()
+    print(sb.create_preview_link(8000).url)
+```
+
+Background commands:
+
+```python
+sb = flax.create_sandbox(template="node")
+job = sb.run("npm install", background=True)
+done = sb.wait(job, timeout=600)
+print(done.status, done.exit_code)
+```
+
+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.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")
+```
+
+Stateful sessions — working directory and exported env persist across commands:
+
+```python
+with sb.create_session() as s:        # auto-deletes on exit
+    s.run("cd /workspace && export TOKEN=abc")
+    print(s.run("pwd").stdout)         # /workspace
+    print(s.run("echo $TOKEN").stdout) # abc
+```
+
+Streaming — live combined stdout/stderr as the command runs:
+
+```python
+stream = sb.run_stream("for i in 1 2 3; do echo $i; sleep 1; done")
+for chunk in stream:
+    print(chunk, end="", flush=True)
+print("exit:", stream.exit_code)
+```
+
+Async client:
+
+```python
+import asyncio
+from flaxcloud import AsyncFlaxClient
+
+async def main():
+    async with AsyncFlaxClient() as flax:
+        async with await flax.create_sandbox(template="python") as sb:
+            print((await sb.run("echo hi")).stdout)
+
+asyncio.run(main())
+```
+
+Errors are typed (`FlaxAuthError`, `FlaxNotFoundError`, `FlaxQuotaError`, …), all subclasses of
+`FlaxError`. The client retries transient failures, sends a versioned `User-Agent`, and ships
+type hints (`py.typed`).
+
+## CLI
+
+```bash
+flax login
+flax sandbox create --template python --startup "python3 -m http.server 8000 --bind 0.0.0.0"
+flax sandbox ls
+flax run sbx_abc123 "python3 -c 'print(6*7)'"
+flax run sbx_abc123 "make build" --stream         # stream output live
+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 preview sbx_abc123 8000
+flax sandbox rm sbx_abc123
+```
+
+`flax --help` lists every command.

flaxcloud-0.3.0/README.md

@@ -0,0 +1,115 @@
+# flaxcloud — Python SDK & CLI for Flax Cloud
+
+Programmatic access to [Flax Cloud](https://flaxcloud.com) isolated sandboxes: create them,
+run commands, move files, preview servers, and wire them into agents/automation.
+
+## Install
+
+```bash
+pip install flaxcloud
+```
+
+## Authenticate
+
+Get an API key from the dashboard, then either set an environment variable or log in with the
+CLI (which stores it in `~/.config/flax/config.json`):
+
+```bash
+export FLAX_API_KEY=flax_live_...
+# or
+flax login
+```
+
+## SDK
+
+```python
+from flaxcloud import FlaxClient
+
+flax = FlaxClient()  # reads FLAX_API_KEY
+
+# create_sandbox returns a handle with methods; use it as a context manager to auto-destroy
+with flax.create_sandbox(template="python") as sb:
+    out = sb.run("python3 -c 'print(6*7)'")
+    print(out.stdout)          # "42\n"
+
+    sb.upload("/workspace/app.py", "print('hello')\n")
+    print(sb.run("python3 app.py").stdout)
+
+    # long-running server + a shareable preview link
+    sb.set_startup("python3 -m http.server 8000 --bind 0.0.0.0")
+    sb.run_startup()
+    print(sb.create_preview_link(8000).url)
+```
+
+Background commands:
+
+```python
+sb = flax.create_sandbox(template="node")
+job = sb.run("npm install", background=True)
+done = sb.wait(job, timeout=600)
+print(done.status, done.exit_code)
+```
+
+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.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")
+```
+
+Stateful sessions — working directory and exported env persist across commands:
+
+```python
+with sb.create_session() as s:        # auto-deletes on exit
+    s.run("cd /workspace && export TOKEN=abc")
+    print(s.run("pwd").stdout)         # /workspace
+    print(s.run("echo $TOKEN").stdout) # abc
+```
+
+Streaming — live combined stdout/stderr as the command runs:
+
+```python
+stream = sb.run_stream("for i in 1 2 3; do echo $i; sleep 1; done")
+for chunk in stream:
+    print(chunk, end="", flush=True)
+print("exit:", stream.exit_code)
+```
+
+Async client:
+
+```python
+import asyncio
+from flaxcloud import AsyncFlaxClient
+
+async def main():
+    async with AsyncFlaxClient() as flax:
+        async with await flax.create_sandbox(template="python") as sb:
+            print((await sb.run("echo hi")).stdout)
+
+asyncio.run(main())
+```
+
+Errors are typed (`FlaxAuthError`, `FlaxNotFoundError`, `FlaxQuotaError`, …), all subclasses of
+`FlaxError`. The client retries transient failures, sends a versioned `User-Agent`, and ships
+type hints (`py.typed`).
+
+## CLI
+
+```bash
+flax login
+flax sandbox create --template python --startup "python3 -m http.server 8000 --bind 0.0.0.0"
+flax sandbox ls
+flax run sbx_abc123 "python3 -c 'print(6*7)'"
+flax run sbx_abc123 "make build" --stream         # stream output live
+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 preview sbx_abc123 8000
+flax sandbox rm sbx_abc123
+```
+
+`flax --help` lists every command.

flaxcloud-0.3.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "flaxcloud"
+version = "0.3.0"
+description = "Python SDK and CLI for Flax Cloud — isolated cloud sandboxes."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [{ name = "Flax Cloud" }]
+keywords = ["flax", "sandbox", "cloud", "agents", "code execution"]
+dependencies = ["httpx>=0.24"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://flaxcloud.com"
+Documentation = "https://github.com/tomitokko/flax-cloud/blob/main/docs/user/sdk.md"
+Source = "https://github.com/tomitokko/flax-cloud"
+Issues = "https://github.com/tomitokko/flax-cloud/issues"
+
+[project.scripts]
+flax = "flaxcloud.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/flaxcloud"]

flaxcloud-0.3.0/src/flaxcloud/__init__.py

@@ -0,0 +1,59 @@
+"""Flax Cloud — Python SDK and CLI for isolated cloud sandboxes.
+
+```python
+from flaxcloud import FlaxClient
+
+flax = FlaxClient()                       # reads FLAX_API_KEY
+with flax.create_sandbox(template="python") as sb:
+    print(sb.run("python3 -c 'print(6*7)'").stdout)
+```
+"""
+
+from __future__ import annotations
+
+from .client import FlaxClient
+from .errors import (
+    FlaxAuthError,
+    FlaxBadRequestError,
+    FlaxConflictError,
+    FlaxConnectionError,
+    FlaxError,
+    FlaxNotFoundError,
+    FlaxQuotaError,
+    FlaxServerError,
+)
+from .models import Command, FileEntry, PreviewLink, SessionResult, StartupStatus
+from .sandbox import Sandbox, Session
+
+__version__ = "0.3.0"
+
+
+def __getattr__(name: str):
+    # Lazily expose the async client so importing the package doesn't require asyncio setup.
+    if name in ("AsyncFlaxClient", "AsyncSandbox"):
+        from . import aio
+
+        return getattr(aio, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "FlaxClient",
+    "Sandbox",
+    "Session",
+    "SessionResult",
+    "AsyncFlaxClient",
+    "AsyncSandbox",
+    "Command",
+    "FileEntry",
+    "PreviewLink",
+    "StartupStatus",
+    "FlaxError",
+    "FlaxAuthError",
+    "FlaxNotFoundError",
+    "FlaxQuotaError",
+    "FlaxConflictError",
+    "FlaxBadRequestError",
+    "FlaxServerError",
+    "FlaxConnectionError",
+]