upstash-box-py

Install upstash-box with pip and call Box.create with a runtime such as node or python. Set the UPSTASH_BOX_API_KEY environment variable or pass api_key to the constructor, then use box.exec, box.files, and box.git to work inside the container.

Call box.agent.run with a prompt and a response_schema set to a Pydantic BaseModel subclass. The run returns a typed result instance along with status and cost, and you can stream output with box.agent.stream or attach a webhook for fire-and-forget runs.

Yes, the SDK ships AsyncBox with an API identical to the sync Box, using await and async for. You can pass many AsyncBox.create or agent.run calls to asyncio.gather to run multiple boxes in parallel.

EphemeralBox is a lightweight, short-lived container with a TTL of up to 3 days that supports exec, files, cd, network policy, and snapshots. It does not support agents or git, so use the full Box when you need AI agent runs or repository operations.

The exit_code field is only populated for exec command runs, not agent runs. Agent runs report their outcome through run.status, which can be completed, failed, cancelled, or detached.

Yes, call box.get_public_url with a port number to get a public preview URL. You can optionally enable bearer token or basic authentication, list all public URLs, and delete them when finished.