Install & Compatibility
Where this runs
tested against v1.31.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.186s · 39.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.5s · import 1.082s · 38MB
37MB installed
● package 37MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
RunloopSDK
✓ from runloop_api_client import RunloopSDK
Use this for the higher-level, object-oriented synchronous API client.
AsyncRunloopSDK
✓ from runloop_api_client import AsyncRunloopSDK
Use this for the higher-level, object-oriented asynchronous API client, recommended for performance.
Runloop
✓ from runloop_api_client import Runloop
Use this for direct access to the lower-level REST API client. The SDK interfaces (RunloopSDK/AsyncRunloopSDK) are generally preferred.
This quickstart demonstrates how to initialize the `AsyncRunloopSDK` client, create a Devbox, execute a command within it, and then properly shut down the Devbox. Ensure your `RUNLOOP_API_KEY` is set as an environment variable for authentication.
import asyncio
import os
from runloop_api_client import AsyncRunloopSDK
async def run_example():
# API Key is auto-loaded from "RUNLOOP_API_KEY" env var by default.
# Ensure RUNLOOP_API_KEY is set in your environment (e.g., export RUNLOOP_API_KEY="your_api_key_here")
# or pass it explicitly: AsyncRunloopSDK(bearer_token="your_api_key_here")
runloop = AsyncRunloopSDK(bearer_token=os.environ.get('RUNLOOP_API_KEY', ''))
devbox = None # Initialize devbox to None for finally block
try:
# Create a devbox and wait for it to be ready
devbox = await runloop.devbox.create()
print(f'Created Runloop Devbox: {devbox.id}')
# Execute a command and wait for it to complete
result = await devbox.cmd.exec(command="echo 'Hello from Runloop!!'")
print(f'Output: {await result.stdout()}')
print(f'Exit code: {result.exit_code}')
except Exception as e:
print(f"An error occurred: {e}")
finally:
if devbox:
print(f'Shutting down Devbox: {devbox.id}')
await devbox.shutdown()
if __name__ == "__main__":
# Ensure the RUNLOOP_API_KEY environment variable is set.
if not os.environ.get('RUNLOOP_API_KEY'):
print("Warning: RUNLOOP_API_KEY environment variable is not set.")
print("Please set it (e.g., export RUNLOOP_API_KEY='your_api_key_here') before running.")
asyncio.run(run_example())
Debug
Known issues
deprecatedThe `blueprints.preview()` method has been deprecated.fixReview the latest documentation for blueprint management for alternative or updated methods. It is listed as deprecated in API specs.
affects: >=1.16.0
breakingMigration from an older 'API Client' to the current `RunloopSDK` structure may require updating import paths and method calls. For instance, `runloop.secrets` has moved to `runloopSDK.api.secrets`.fixUpdate imports from `Runloop` to `RunloopSDK` or `AsyncRunloopSDK` and adjust method calls to use the `sdk.api` property for direct REST API access or the object-oriented interfaces (e.g., `sdk.devbox`).
affects: Potentially older versions to current `RunloopSDK` based versions.
gotchaAuthentication primarily relies on the `RUNLOOP_API_KEY` environment variable. If not set, the client may fail to authenticate or you'll need to pass the `bearer_token` explicitly.fixAlways ensure the `RUNLOOP_API_KEY` environment variable is set before initializing the client, or explicitly pass `bearer_token` during client instantiation: `RunloopSDK(bearer_token="your_key")`.
affects: All versions
gotchaDevboxes are persistent resources. Failing to explicitly shut down a `Devbox` using `await devbox.shutdown()` (or using a context manager with `with runloop.devbox.create(...)`) can lead to lingering resources and unexpected costs.fixAlways call `await devbox.shutdown()` or use a `with` statement with `runloop.devbox.create()` for proper resource cleanup.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'runloop'
The user attempted to import from a module named 'runloop', but the correct module name for the `runloop-api-client` package is `runloop_api_client`.
fixfrom runloop_api_client import RunloopSDK, AsyncRunloopSDK
ValueError: API key not provided. Set RUNLOOP_API_KEY environment variable or pass api_key parameter.
The RunloopSDK client was instantiated without providing an API key either directly via the `api_key` parameter or through the `RUNLOOP_API_KEY` environment variable.
fixclient = RunloopSDK(api_key="YOUR_RUNLOOP_API_KEY")
AttributeError: 'RunloopSDK' object has no attribute 'devbox'
The user attempted to access a resource collection (e.g., for Devboxes) using a singular attribute name, while the SDK expects a plural attribute name for resource managers.
fixclient.devboxes.list()
TypeError: object AsyncRunloopSDK.devboxes.list is not awaitable
An asynchronous method (e.g., `list` from `AsyncRunloopSDK`) was called without using the `await` keyword within an `async` function.
fixawait client.devboxes.list()
Upgrade
Version history
1.31.0latest on PyPI · released Aug 25, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.9 or higher for compatibility.
aiohttpoptionalOptional dependency for improved concurrency performance with the asynchronous client.