Pods

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,
)

uv run lazycloud deploy tools:web

The deploy runs the pod in the cloud and prints the HTTPS URL of its http port. Pods are public by default; authorized=True makes the URL take the same bearer token as an endpoint. A pod fits when you already have a command or image to run, as the LoRA fine-tuning example does for vLLM. For Python you want to call as a function or serve over HTTP, an endpoint needs less setup.

Keep a container up

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.

Run more than one container

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.

Configure the container

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.
`ssh`	Serve SSH through `lazycloud ssh`. `app.devbox` sets it up for a devbox.
`disks`	Durable disks; a pod with one runs one container.

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

Expose a raw TCP port

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.releases[0].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 a pod

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.

Set what every workload shares

Images, resources, and scaling.

Getting started

Core concepts

CLI reference

Examples

Account