Metadata-Version: 2.4
Name: runcloud-sdk
Version: 0.9.0
Summary: Python SDK for run.cloud, including sandbox-provider compatibility adapters
Author: Newly
License-Expression: Apache-2.0
Project-URL: Homepage, https://run.cloud
Project-URL: Documentation, https://docs.run.cloud
Project-URL: Repository, https://github.com/newly-app/newly/tree/main/run-cloud/python-sdk
Keywords: runcloud,run-cloud,sandbox,microvm,firecracker,sdk
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: websockets<16,>=13
Dynamic: license-file

# runcloud

Python SDK for [run.cloud](https://run.cloud).

```bash
pip install runcloud-sdk
runcloud login
```

```python
from runcloud import Client

cloud = Client()
box = cloud.create(image="runcloud/agent-base", cpu=2, memory=4096)
try:
    result = box.exec("python -V")
    print(result.stdout)
finally:
    box.destroy()
```

Commands started through the Modal compatibility adapter stream output while
they are running:

```python
from runcloud.compat import modal

app = modal.App.lookup("my-app")
box = modal.Sandbox.create(app=app)
try:
    process = box.exec(
        "bash",
        "-c",
        "for i in {1..5}; do date +%T; sleep 0.5; done",
    )
    for line in process.stdout:
        print(line, end="")
    process.wait()
finally:
    box.terminate()
```

`Client()` automatically uses the credential saved by `runcloud login`. For
automation, set `RUN_CLOUD_API_KEY` and optionally `RUN_CLOUD_API_URL`, or pass
`api_key` and `api_url` directly.

A sandbox's name is a label you own: set it at create, change it later, and
filter on it. Naming plus `resume` is how the same sandbox goes back to the same
piece of work instead of booting a new one:

```python
matches = cloud.list(name=f"project-{project_id}")
box = matches[0].resume() if matches else cloud.create(name=f"project-{project_id}")

box.rename(f"project-{project_id}-v2")
box.rename("")  # clears the label
```

Names are not unique and mean nothing to the platform, so check `state` on a
match before using it. Renaming works in any state but `destroyed`.

## Compatibility adapters

The same distribution includes migration adapters:

| Provider | Import |
| --- | --- |
| Modal | `from runcloud.compat import modal` |
| E2B | `from runcloud.compat.e2b import Sandbox` |
| Daytona | `from runcloud.compat.daytona import Daytona` |
| Vercel Sandbox | `from runcloud.compat.vercel import Sandbox` |
| Blaxel async | `from runcloud.compat.blaxel import SandboxInstance` |
| Blaxel sync | `from runcloud.compat.blaxel import SyncSandboxInstance` |
| Fly Sprites | `from runcloud.compat.sprites import SpritesClient` |

Adapters cover creation, command execution, lookup/listing, and destruction
where the upstream SDK exposes them. Blaxel's current `SandboxInstance` API is
async; `SyncSandboxInstance` preserves its synchronous API. Unsupported
provider-specific features raise `UnsupportedCompatibilityFeatureError` with a
migration hint. They do not silently pretend that run.cloud implements a
provider-specific feature.
