Skip to main content

Cloudex SDK for Python

Create, fork and drive Cloudex sandboxes: agent computers in your own Cloudflare account. Python 3.9+, standard library only.

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.

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; servers on localhost work too
box.links(), box.revoke_links(port=None) The links that work; make one port's link, or all of them, stop working
box.update(name=, idle_minutes=) Rename, or change the idle time
box.desktop(size=), box.stop_desktop() Start the desktop (Chrome, a terminal) and get a link to it
box.stop(), box.resume(from_backup=, size=), box.delete() Save and stop, start again (on another size with size), 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.

Metadata

Release files for cloudex 0.1.15

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cloudex 0.1.15
File Size Uploaded Provenance Actions
cloudex-0.1.15.tar.gz 13.1 kB With provenance Details for cloudex-0.1.15.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cloudex 0.1.15
File Interpreter ABI Platform Actions
cloudex-0.1.15-py3-none-any.whl Python 3 none any Details for cloudex-0.1.15-py3-none-any.whl

Total release size: 23.8 kB

Release files / cloudex-0.1.15.tar.gz

Download URL cloudex-0.1.15.tar.gz
Size 13.1 kB
Tags Source
SHA-256 checksum
How to use checksums
1ab1cc911957256aa1050de00d067eccb8c81011703d6d655c0c1f51b8f63565
BLAKE2b-256 checksum
How to use checksums
c45fa74cf7869a916a249eae23b198b8723f49a0e305d0a4d14a75b3c2be306e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

Release files / cloudex-0.1.15-py3-none-any.whl

Download URL cloudex-0.1.15-py3-none-any.whl
Size 10.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0619b02c33e1aac4a191d30dacc0f0edbbe70c3fbcacd1a25343a512b9f1bad9
BLAKE2b-256 checksum
How to use checksums
8ae2f28f5e2b95abb69711d19be98b7707615f4f91251ccf84b31adee03ad35f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

Security for cloudex 0.1.15

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for cloudex-0.1.15.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page