vxcloud · Python SDK

Provision infrastructure, deploy applications, and manage running services on the vxcloud platform — straight from Python.

vxcloud is the official, brand-name distribution of the vxcloud Python SDK. It re-exports the entire vxsdk surface, so import vxcloud and import vxsdk are byte-for-byte identical — pick the name your team prefers. The sync client is stdlib-only (zero third-party dependencies); an optional async client is one extra away.

Installation · Quick start · What you can do · Async · Errors · Docs

Installation

pip install vxcloud            # sync client — stdlib only, zero dependencies
pip install vxcloud[async]     # adds httpx for the async client

Requires Python 3.9+. Tested on CPython 3.9 – 3.12.

Quick start

import vxcloud

# Reads ~/.vxcloud/credentials.json (written by `vxcli auth login`)
c = vxcloud.Client.load_from_vxcli()

# ...or pass credentials explicitly
# c = vxcloud.Client(api_key="xc_dev_...", username="alice")

# Provision a VM on AWS
vm = c.cloud.vm.provision(
    name="api-vm", cloud="aws", region="us-east-1",
    instance_type="t3.small", key_pair_name="AWSPRODKEY2",
)
print(vm["public_ip"])

# Deploy a Docker container onto it
result = c.deploy.container(
    host=vm["public_ip"], ssh_user="ubuntu", key_pair_name="AWSPRODKEY1.PEM",
    image="grafana/grafana:latest", name="grafana",
    ports=["3000:3000"], restart_policy="unless-stopped",
)
print(result["session_id"], result.get("status"))

Pick the entry-point name you like

All four resolve to the same client class — there is no behavior difference:

import vxcloud

c = vxcloud.Client.load_from_vxcli()      # canonical
c = vxcloud.VxCloud.load_from_vxcli()     # PascalCase brand (matches the TS SDK)
c = vxcloud.vxcloud.load_from_vxcli()     # lowercase brand
c = vxcloud.load_from_vxcli()             # module-level convenience

What you can do

vxcloud is a thin, typed wrapper over the vxcloud FastAPI control plane. The same JSON wire contract powers the Go and TypeScript SDKs.

# Deploy a language stack straight from a public git repo
c.deploy.stack(
    "golang",
    host="54.197.71.181", ssh_user="ubuntu", key_pair_name="AWSPRODKEY1.PEM",
    repo_url="https://github.com/joelwembo/va-sample-golang.git", branch="main",
    git_provider="github", app_name="va-sample-golang",
    http_port="80", app_port="8080", go_version="1.22",
)

# Trigger a CI/CD pipeline
for p in c.cicd.pipelines.list():
    print(p["id"], p["name"])
build = c.cicd.pipelines.trigger(pipeline_id="abc...", branch="main")

# Deploy a marketplace agent
c.marketplace.agents.deploy(
    "golang_url_status_agent",
    host="54.197.71.181", ssh_user="ubuntu", key_pair_name="AWSPRODKEY1.PEM",
    http_port="8094",
)

Async flavor

Install the extra and switch Client → AsyncClient. Same classes, same method signatures — just add async/await. Ideal for FastAPI/aiohttp services and concurrent fan-out (multi-host deploys, batch installs).

import asyncio
import vxcloud_async as vx

async def main():
    async with await vx.AsyncClient.load_from_vxcli() as c:
        # Three deploys in parallel — ~2.5× faster than sequential
        await asyncio.gather(
            c.deploy.container(host=h1, ssh_user="ubuntu", key_pair_name=K, image="redis:7", ports=["6381:6379"], name="r1"),
            c.deploy.container(host=h2, ssh_user="ubuntu", key_pair_name=K, image="redis:7", ports=["6381:6379"], name="r2"),
            c.deploy.container(host=h3, ssh_user="ubuntu", key_pair_name=K, image="redis:7", ports=["6381:6379"], name="r3"),
        )

asyncio.run(main())

Error handling

try:
    c.cicd.pipelines.list()
except vxcloud.VxAuthError:        # 401 / 403
    ...
except vxcloud.VxValidationError:  # 400 / 422
    ...
except vxcloud.VxRateLimitError as e:   # 429 — inspect e.retry_after
    ...
except vxcloud.VxNotFoundError:    # 404
    ...
except vxcloud.VxServerError:      # 5xx
    ...
except vxcloud.VxNetworkError:     # transport-level
    ...
except vxcloud.VxError:            # base class — anything else
    ...

The client automatically retries transient failures (VxNetworkError, VxServerError, VxRateLimitError) up to 3 times with exponential backoff, and transparently refreshes an expired API key on 401 before replaying the request — so application code rarely sees token expiration. Auth and validation errors are surfaced immediately.

vxcloud vs. vxsdk

Links

• 📦 PyPI: pypi.org/project/vxcloud · pypi.org/project/vxsdk
• 📖 Documentation: vxcloud.io/docs/sdks
• 🛠️ Source & issues: github.com/prodxcloud/vxcloud
• 📝 Changelog: CHANGELOG.md

License

Apache-2.0 © vxcloud / ProdXCloud