feat: add sync and async sandbox SDK

[KAJdev]

This brings sandbox support to the Python SDK, with a regular Sandbox API and an async AsyncioSandbox API. Both share the same lifecycle and execution logic.

use a context manager for a short-lived sandbox:

from runpod import Sandbox

with Sandbox(image_name="python:3.12-slim") as sandbox:
    result = sandbox.exec(["python", "-c", "print('hello from the sandbox')"], check=True)
    print(result.output)

The async version works the same way:

import asyncio
from runpod import AsyncioSandbox

async def main():
    async with AsyncioSandbox(image_name="python:3.12-slim") as sandbox:
        result = await sandbox.exec(["python", "-c", "print('hello')"], check=True)
        print(result.output)

asyncio.run(main())

To work with a sandbox that's already running, use get(sandbox_id) or list(...). Those handles only close their local connections when you leave the context. they don't terminate the sandbox. You can call terminate() explicitly when you're finished with it.

exec() returns command output, and check=True raises on command failure while keeping any partial output. logs() streams container or system logs and supports resuming with an event's id through last_event_id. Use a context manager around the log stream too if you might stop reading early.

While working on this, I discovered an edge case in log streaming on host that should be addressed as well: CON-1557 / runpod/host#2820.

Linear: CON-1523, CON-1524, CON-1525, CON-1526

[runpod-Henrik]

QA review of the SDK surface, diff only.

Good call on ExecResult(output=data["output"], error=data.get("error")). A successful exec omits the error key entirely rather than sending null, despite the OpenAPI text describing it as "null when the command succeeded" — a strict is None comparison there reported every real success as a failure in another consumer, with green unit tests the whole time. Using .get() sidesteps it. Worth a comment on that line so nobody "tidies" it into an is None check later.

Four things.

1. AsyncioSandbox vs the specified AsyncSandbox

The design doc names the async entry point AsyncSandbox, and the stated reason is specific rather than aesthetic: it matches E2B's exact class name, so developers arriving from E2B or Daytona don't have to relearn a term. AsyncioSandbox gives up precisely that benefit.

The PR is also internally split on it — __all__ exports AsyncioSandbox alongside AsyncSandboxLogStream, so both prefixes ship in the same namespace. Whichever way this goes, the two should agree.

This is cheap to change now and a breaking change later, which is why it's worth settling before merge rather than after.

2. check: bool = False inverts the documented default

The design doc lists the raise-on-failure default as an open question and records the lean as raising. This ships the opposite: a command that exits non-zero returns an ExecResult and execution continues unless the caller opted in.

Two honest sides to this. check is the better name — it matches subprocess.run, and Python developers will read it correctly with no docs. But the default matters more than the name for this product: the entire use case is executing code a model just wrote, where silently proceeding past a failed command is how an agent ends up building on a step that didn't happen. E2B and the other SDKs in this category raise by default.

Not asking for a specific answer, just that the default is chosen deliberately and recorded, rather than inherited from subprocess.

3. This is the public repo

Shipping sandbox support into public runpod-python while the feature is email-gated and dark in prod means users can discover, install and build against an API that isn't generally available yet. That's happened before on another product and produced support load plus pressure not to change the surface — which is exactly the surface still being decided in points 1 and 2.

Options are a private repo until GA, or release tagging that keeps it off the default install. Either is fine; drifting into GA by publication is the one to avoid.

4. data["output"] is a hard index on a 200

output is required in the schema, so this is spec-correct. The failure mode it misses is a malformed 200 that isn't the API at all — a proxy error page, an HTML interstitial — which raises KeyError rather than anything a caller can act on. Another consumer of this endpoint hit exactly that shape on create. A .get("output", "") with an explicit error, or letting the existing response validation catch it, turns a confusing traceback into a real message.

Not gaps, for the record

No upload_file / download_file: there are no file-transfer endpoints in the REST contract yet, so that's blocked upstream rather than missing here. Same for anything depending on streaming exec.

[Copilot]

Copilot review overview

🟡 Changes recommended

It introduces a couple of correctness/compatibility concerns in newly added public API and transport code that should be addressed before merging.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1 · 1

Open (2)

• Guard private aiohttp retry attribute assignment · New
• Model vcpu_count as an integer · New

What changed in this PR

This PR introduces first-class sandbox support to the Runpod Python SDK by adding parallel sync (Sandbox) and async (AsyncioSandbox) APIs that share the same lifecycle semantics, command execution behavior, and log streaming facilities over REST API v2.

Changes:

• Added async sandbox handle (AsyncioSandbox) with lifecycle management, exec semantics (check=True), and resumable SSE log streaming.
• Added sync wrapper (Sandbox) backed by a dedicated background asyncio loop to safely reuse aiohttp sessions while presenting a blocking API.
• Added integration-style tests and README documentation for sandbox creation, borrowed handles (get/list), exec retry rules, and log streaming.

File	Description
tests/​test_sandbox.py	Adds HTTP-level regression tests for sandbox lifecycle edge cases, exec retry semantics, and SSE log streaming behavior.
tests/​test_init.py	Removes a brittle __all__ exact-match assertion that would conflict with newly exported sandbox symbols.
runpod/​sandbox/​sync.py	Implements the blocking Sandbox facade and sync log iterator over a stable background event loop.
runpod/​sandbox/​models.py	Introduces typed models for sandbox snapshots, exec results, log events, and sandbox-specific exceptions.
runpod/​sandbox/​asyncio.py	Implements AsyncioSandbox lifecycle, startup retry policy, exec behavior, and typed async log streaming.
runpod/​sandbox/​__init__.py	Exports sandbox public API surface from the runpod.sandbox package.
runpod/​api/​sandboxes.py	Adds aiohttp-based REST + SSE transport for sandboxes (create/get/list/terminate/exec/logs).
runpod/​api/​rest.py	Extends URL building to support custom base URLs and centralizes HTTP-status-to-error mapping for reuse.
runpod/​__init__.py	Exposes Sandbox and AsyncioSandbox from the top-level runpod package and updates __all__.
README.md	Documents sync/async sandbox usage, lifecycle semantics, exec/check behavior, and log streaming/resume.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.