Pods

A pod fits when you already have a command or image to run. For Python you want to call as a function or serve over HTTP, an endpoint needs less setup.

Define a pod

Save this as tools.py:

from lazycloud import App, Image

app = App("tools")

web = app.pod(
    name="web",
    image=Image(python_version="3.12"),
    command=["python", "-m", "http.server", "8080"],
    ports={"http": 8080},
    cpu=0.5,
    memory="256Mi",
    authorized=True,
)

Pods are public by default. authorized=True makes the URL take the same bearer token as an endpoint.

Deploy it

lazycloud deploy runs the pod in the cloud and prints its URL. The vLLM example deploys a model server this way.

uv run lazycloud deploy tools:web

A deployed pod runs one container while it has connections and stops it after keep_warm seconds idle, 600 by default. keep_warm=-1 keeps one up at all times, which suits a model server that can’t wait for a cold start. Pods don’t autoscale, so more containers means a count:

uv run lazycloud deployment scale web --containers 2

The count holds until the next scale, and web.scale(n) does the same from Python.

Create an instance on demand

A pod can also run once without a deployment. With an access token in LAZYCLOUD_TOKEN, this starts an instance, fetches the directory listing, and stops it:

import os
import urllib.request

from tools import web

instance = web.create()
try:
    request = urllib.request.Request(
        instance.url,
        headers={"Authorization": f"Bearer {os.environ['LAZYCLOUD_TOKEN']}"},
    )
    with urllib.request.urlopen(request, timeout=60) as response:
        print(response.read().decode())
finally:
    instance.terminate()

web.run("python", "--version") starts one with a different command. An instance has a url and terminate(), and lives for keep_warm seconds unless timeout_seconds says otherwise.

Pod options

Option	What it does
`command`, `ports`	What runs, and the named ports it listens on, such as `{"http": 8080}`.
`health_check_path`, `health_check_port`	An HTTP probe that must pass before traffic arrives.
`block_network`, `allow_list`	Cut outbound access, or limit it to CIDR ranges.
`checkpoint_enabled`	Allow checkpoints, gated by `checkpoint_readiness_path` and `_port`.
`docker_enabled`	Give the pod its own Docker daemon.

env, secrets, volumes, and machine work as on every workload, and web.shell() opens a shell in a pod container.

TCP connections

tcp=True exposes a raw TCP port at a tls://hostname:port address. Clients connect with TLS and send that hostname as SNI. TCP pods are always public, so the server authenticates its own clients.

import socket
import ssl
from urllib.parse import urlsplit

from lazycloud import App, Image

app = App("tcp_example")
tcp_server = app.pod(
    name="tcp-web",
    image=Image(python_version="3.12"),
    command=["python", "-m", "http.server", "8080"],
    ports={"http": 8080},
    tcp=True,
    authorized=False,
)

deployment = tcp_server.deploy()
address = urlsplit(deployment.invoke_url)
with socket.create_connection((address.hostname, address.port)) as connection:
    with ssl.create_default_context().wrap_socket(
        connection, server_hostname=address.hostname
    ) as stream:
        stream.sendall(b"GET / HTTP/1.0\r\n\r\n")
        print(stream.recv(1024))

Stop and clean up

uv run lazycloud deployment stop web
uv run lazycloud deployment delete web

stop keeps the definition and delete removes it, like web.pause() and web.delete() in Python. A running deployment replaces any container you stop by hand, so stopping the deployment is what keeps a pod down.

Shared settings

Images, resources, and scaling.

Getting started

Core concepts

CLI reference

Examples

Account

Define a pod

Deploy it

Create an instance on demand

Pod options

TCP connections

Stop and clean up

Shared settings

​Define a pod

​Deploy it

​Create an instance on demand

​Pod options

​TCP connections

​Stop and clean up

​Shared settings

Define a pod

Deploy it

Create an instance on demand

Pod options

TCP connections

Stop and clean up

Shared settings