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, set RUNTIME_API_KEY from your secret manager (create a key 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. 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, files (read, write, list, glob, stat, move, remove, upload and download directories), pause, wake, extend, fork and snapshot, and the interpreter, network, previews and desktop products. 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.

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

The package was called withruntime-cloud, imported as runtime_cloud, until 0.3.0. Both names still work: withruntime-cloud installs this package and import runtime_cloud gives you the same classes.