Runtime Cloud Python SDK

One client for every Runtime Cloud product, sync and async. Python 3.10 or later, standard library only.

pip install withruntime

The client uses RUNTIME_API_KEY when it is set, and otherwise the connection this machine saved when npx withruntime login connected it (one browser approval, no key to copy). On a server or a CI runner, set RUNTIME_API_KEY from your secret manager: npx withruntime keys create prints a new key once after an owner, admin or developer of the account approves it in the browser, or create one at https://withruntime.com/account/keys. Never put a key in source code, a URL or a command-line argument.

from withruntime import Sandbox

with Sandbox.create() as sbx:
    result = sbx.exec("python3 -c 'print(6 * 7)'")
    print(result.exit_code, result.stdout)

Sandbox.create() needs no arguments and returns once the sandbox is running; leaving the with block stops it. With no arguments you get the free trial while it lasts: 100 free hours, no card, up to eight sandboxes running at once. The current default image includes NumPy, pandas and matplotlib; see the sandbox environment. AsyncRuntime is the same client for asyncio, method for method:

import asyncio
from withruntime import AsyncRuntime


async def main():
    async with AsyncRuntime() as runtime:
        async with await runtime.sandboxes.create() as sbx:
            print((await sbx.exec("uname -a")).stdout)


asyncio.run(main())

A sandbox has exec, exec_stream, spawn, terminal, forward_port (any TCP port in the sandbox on a local port), files (read, write, list, glob, stat, move, remove, upload and download directories), pause, wake, extend, update, keep_alive, fork and snapshot, and the interpreter, network, previews and desktop products. A paused sandbox also wakes by itself on the next call, and Sandbox.get_or_create(name) returns the sandbox with that name or creates it. A sandbox pauses itself after 60 seconds with nothing happening in it, keeping its memory and processes, so an idle sandbox costs no compute; idle_pause_seconds sets 10 to 86,400, or 0 for never. The client has sandboxes, images, volumes, snapshots, limits, feedback and support; runtime.limits.get() (0.3.1 and later) says whether the key is read-only and what its agent may still spend today. Every write carries an idempotency key, so retries never do anything twice; errors are typed and carry code, hint and request_id.

Behind a proxy

The client reads HTTPS_PROXY, HTTP_PROXY and NO_PROXY (upper or lower case; lower wins when both are set), sync and async. Calls to the API and terminal WebSockets go through HTTPS_PROXY as a CONNECT tunnel, with any user:password@ in its address sent to the proxy. HTTP_PROXY is used only for http:// addresses, never for the HTTPS API. NO_PROXY lists hosts to reach directly, split by commas or spaces: a name covers its subdomains, a leading dot is allowed, host:port limits it to one port, and * means every host. A proxy address without a scheme is http://; only http:// proxies are supported, and anything else fails at once with invalid_proxy. When a call cannot get through, the error names the proxy it tried (without the password), for example No answer from Runtime at https://api.withruntime.com through the proxy http://proxy.internal:3128 (HTTPS_PROXY).

Code written for E2B

withruntime.e2b runs code written for E2B's Python SDK on Runtime. Change the import and set RUNTIME_API_KEY:

from withruntime.e2b import Sandbox, AsyncSandbox  # was: from e2b import ...
from withruntime.e2b.code_interpreter import Sandbox  # was: from e2b_code_interpreter import Sandbox

Sandboxes get E2B's defaults: 2 vCPU, 512 MiB and a 300-second timeout. Timeouts are in seconds, as in E2B's Python SDK. runtime_create={...} passes Runtime's own create fields, for example {"funding": "trial"}. What Runtime does not do the way E2B does raises NotSupportedException before anything happens, naming what to use instead. Importing withruntime alone does not load it. The sync Sandbox is generated from the async one by scripts/generate_e2b_sync.py.

Code written for Daytona or Vercel Sandbox

withruntime.daytona and withruntime.vercel do the same for Daytona's Python SDK and Vercel Sandbox's. Change the import:

from withruntime.daytona import Daytona, AsyncDaytona  # was: from daytona import ...
from withruntime.vercel import sandbox  # was: from vercel import sandbox
from withruntime.vercel.sandbox import sync as sandbox  # was: from vercel.sandbox import sync as sandbox

Sandboxes get the rival's defaults: Daytona's 1 vCPU, 1 GiB and 3 GiB disk, pausing after 15 minutes without calls; Vercel's 2 vCPUs with 2048 MiB each, 5 minutes, persistent. runtime_create={...} passes Runtime's own create fields. A Daytona or Vercel key is never sent anywhere. What Runtime does not do the same way raises NotSupportedError before anything happens, naming what to use instead. The sync modules are generated from the async ones by scripts/generate_dropin_sync.py. DAYTONA.md and VERCEL.md in the JavaScript package list every mapping and gap.

Code written for Blaxel

withruntime.blaxel runs code written for Blaxel's Python SDK (blaxel 0.4.11) on Runtime. Change the import and set RUNTIME_API_KEY, or run npx withruntime login once:

from withruntime.blaxel import SandboxInstance  # was: from blaxel.core import SandboxInstance
from withruntime.blaxel import SyncSandboxInstance  # was: from blaxel.core import SyncSandboxInstance

withruntime.blaxel.core holds the same names, so replacing blaxel. with withruntime.blaxel. works too. A Runtime key in BL_API_KEY is used; a Blaxel key is never sent anywhere.

How it maps:

• Sandboxes. create, create_if_not_exists (one sandbox when two calls race), get, get_by_external_id, list, delete, fork, snapshots and the update_* calls work. memory is kept, with one vCPU for every 2048 MB. Blaxel's general templates (blaxel/base-image, py-app, ts-app, node, jupyter-server, docker-in-sandbox) run on Runtime's image. Any other image ns/name:tag starts from the ready Runtime image ns-name:tag (every / becomes -; the tag is latest when none is given), so the code keeps Blaxel's image string. A missing one raises NotSupportedError with the build command, for example npx withruntime image build --dockerfile Dockerfile --name my-company-agent-image -t my-company-agent-image:latest. Volumes mount Runtime volumes of the same name. On the free trial a sandbox has at most 4096 MB of memory (2 vCPUs).
• Standby. A sandbox pauses after a minute with no call (Blaxel: about 15 seconds). It keeps its memory and processes, and wakes on the next command, file call or preview visit. archive pauses it and keeps its memory too. A lease in use is renewed, so a long command is not paused at the hour. keep_alive raises the idle pause to the process's time limit, or turns it off for a process with none. The first call from any client that finds no keep_alive process running gives the old idle pause back.
• How long it is kept. A paused sandbox with no ttl or lifecycle is kept 365 days. Blaxel keeps it until you delete it. A limit is rounded up to whole days of pause. A limit of an hour or less that counts from creation also ends the sandbox at that time. On the free trial a paused sandbox is kept seven days, the most Blaxel's first tier keeps one.
• Envs reach every process, from any client: they are kept on the sandbox, and a process's own env wins.
• Paths. /blaxel, Blaxel's working directory and HOME, is /workspace. Relative paths and ~ start there.
• Processes. You can find a process by name from any client, as long as Runtime still has its record. Runtime keeps the running processes and the last 16 that ended.
• Previews are Runtime previews of each port. A private preview's tokens.create(expires_at) gives a token, which works as Blaxel's X-Blaxel-Preview-Token header or bl_preview_token address parameter. fetch(port) uses a private preview for you.
• Code interpreter. CodeInterpreter.run_code and create_code_context run on Runtime's interpreter and return Blaxel's result classes.
• Errors. Errors keep Blaxel's classes: SandboxAPIError, ResponseError and SnapshotAPIError. Each also carries Runtime's code, hint and request_id.
• Runtime fields. runtime_create={...} passes Runtime's own create fields, for example {"funding": "trial"}. sandbox.withruntime is the Runtime sandbox underneath.

Differences you can hit:

• Commands run as root, as on Blaxel, with the sandbox's PATH and HOME (/workspace). File calls act as the sandbox user and fall back to sudo where only root may: they reach files a root process made, including private ones, and a file they write is the sandbox user's.
• A key sees the sandboxes it made, and another key's answer 404, unless an owner or admin makes the key account-wide, as a Blaxel workspace key is (teams).
• Public previews need a paid sandbox.
• A process's pid is Runtime's process id, not an operating-system number.

These raise NotSupportedError before anything happens, naming what to use: regions outside the US, read-only and ephemeral volumes, drives, extra_args other than iptables, egress and subnet settings, preview headers, custom domains and preview expiry, restoring a snapshot in place (fork from it instead), sessions, codegen, system, schedules, and Blaxel's agents, models, tools, jobs and applications. The sync module is generated from the async one by scripts/generate_dropin_sync.py.

Agent frameworks

withruntime.openai_agents is a sandbox client for the OpenAI Agents SDK's SandboxAgent (pip install "withruntime[openai-agents]"), and withruntime.deepagents is a Deep Agents sandbox backend. withruntime.tools gives LangChain, CrewAI, LlamaIndex, Pydantic AI, Google ADK and any framework that takes typed functions four sandbox tools. See https://withruntime.com/docs/frameworks.

Docs: https://withruntime.com/docs/python.

The package was called withruntime-cloud, imported as runtime_cloud, until 0.3.0. That name stopped at 0.5.1 and gets no new releases: use withruntime.