Quickstart
Get the runtime running in a sandbox and connect to it from Python.
Step 1: Start the Runtime in a Sandbox
Inside any sandbox that can run npx and expose a port:
npx -y runtimeuseThis starts a WebSocket server on port 8080 using the OpenAI agent handler by default. To use Claude instead:
npx -y runtimeuse --agent claudeStep 2: Connect from Python
Install the Python client:
pip install runtimeuseConnect to the WebSocket server and invoke the agent:
from runtimeuse import RuntimeUseClient, RuntimeUseInvoker, InvocationMessage, ResultMessageInterface
# Connect to the sandbox's WebSocket server
sandbox = Sandbox.create()
sandbox.run("npx -y runtimeuse")
ws_url = sandbox.get_url(8080)
client = RuntimeUseClient(ws_url=ws_url)
invoker = RuntimeUseInvoker(client)
# Build an invocation
invocation = InvocationMessage(
message_type="invocation_message",
source_id="my-source",
system_prompt="You are a helpful assistant.",
user_prompt="Run the tests.",
output_format_json_schema_str='{"type":"json_schema","schema":{"type":"object"}}',
secrets_to_redact=[],
agent_env={},
)
# Invoke and handle the result
async def on_result(result: ResultMessageInterface):
print(f"Result: {result.structured_output}")
await invoker.invoke(
invocation=invocation,
on_result_message=on_result,
result_message_cls=ResultMessageInterface,
)