API Reference¶

Complete API documentation for NoxRunner.

Client API¶

Modules¶

NoxRunner - Python Client Library for Sandbox Execution Backends

A complete Python client library for interacting with NoxRunner-compatible sandbox execution backends. Uses only Python standard library - zero external dependencies.

Example

>>> from noxrunner import NoxRunnerClient
>>> client = NoxRunnerClient("http://127.0.0.1:8080")
>>> client.create_sandbox("my-session")
>>> result = client.exec("my-session", ["python3", "--version"])
>>> print(result["stdout"])

class noxrunner.NoxRunnerClient(base_url=None, timeout=30, local_test=False)[source]¶

Bases: object

Client for NoxRunner-compatible sandbox execution backends.

This client provides a Python interface to NoxRunner backends, allowing you to create, manage, and interact with sandbox execution environments.

The client uses only Python standard library - no external dependencies required. This makes it suitable for environments where installing third-party packages is restricted or undesirable.

Example

>>> from noxrunner import NoxRunnerClient
>>> client = NoxRunnerClient("http://127.0.0.1:8080")
>>> client.create_sandbox("my-session")
>>> result = client.exec("my-session", ["python3", "--version"])
>>> print(result["stdout"])

__init__(base_url=None, timeout=30, local_test=False)[source]¶

Initialize the NoxRunner client.

Parameters:

base_url (str | None) – Base URL of the NoxRunner backend (e.g., “http://127.0.0.1:8080”). If None or empty and local_test is False, will raise an error. If None or empty and local_test is True, will use local sandbox mode.
timeout (int) – Request timeout in seconds (default: 30)
local_test (bool) – If True, use local sandbox backend for offline testing. WARNING: This executes commands in your local environment!

Example

>>> client = NoxRunnerClient("http://127.0.0.1:8080", timeout=60)
>>> # Or for local testing:
>>> client = NoxRunnerClient(local_test=True)

create_sandbox(session_id, ttl_seconds=900, image=None, cpu_limit=None, memory_limit=None, ephemeral_storage_limit=None)[source]¶

Create or ensure a sandbox execution environment exists.

Parameters:

session_id (str) – Unique session identifier
ttl_seconds (int) – Time to live in seconds (default: 900)
image (str | None) – Container image (optional)
cpu_limit (str | None) – CPU limit (optional, e.g., “1”)
memory_limit (str | None) – Memory limit (optional, e.g., “1Gi”)
ephemeral_storage_limit (str | None) – Ephemeral storage limit (optional, e.g., “2Gi”)

Returns:

Dict with ‘podName’ (or equivalent) and ‘expiresAt’

Raises:

NoxRunnerHTTPError – If request fails

Return type:

dict

Example

>>> result = client.create_sandbox("my-session", ttl_seconds=1800)
>>> print(f"Sandbox: {result.get('podName')}")

delete_sandbox(session_id)[source]¶

Delete a sandbox execution environment.

Parameters:: session_id (str) – Session identifier
Returns:: True if successful
Raises:: NoxRunnerHTTPError – If request fails
Return type:: bool

Example

>>> client.delete_sandbox("my-session")
True

download_files(session_id, src='/workspace')[source]¶

Download files from the sandbox as a tar archive.

Parameters:

session_id (str) – Session identifier
src (str) – Source directory (default: ‘/workspace’)

Returns:

Tar archive as bytes

Raises:

NoxRunnerHTTPError – If request fails

Return type:

bytes

Example

>>> tar_data = client.download_files("my-session")
>>> # Extract tar_data using tarfile

download_workspace(session_id, local_dir, src='/workspace')[source]¶

Download workspace from sandbox to local directory.

This is a convenience method that downloads files from the sandbox and extracts them to a local directory. It handles tar extraction automatically, so you don’t need to deal with tar archives directly.

Parameters:

session_id (str) – Session identifier
local_dir (str | Path) – Local directory path to extract files to
src (str) – Source directory in sandbox (default: ‘/workspace’)

Returns:

True if successful, False otherwise

Raises:

NoxRunnerHTTPError – If request fails
ValueError – If local_dir is invalid

Return type:

bool

Example

>>> client.download_workspace("my-session", "./output")
True
>>> # Files from /workspace in sandbox are now in ./output

exec(session_id, cmd, workdir='/workspace', env=None, timeout_seconds=30)[source]¶

Execute a command in the sandbox.

Parameters:

session_id (str) – Session identifier
cmd (List[str]) – Command to execute (list of strings)
workdir (str) – Working directory (default: ‘/workspace’)
env (Dict[str, str] | None) – Environment variables (optional)
timeout_seconds (int) – Command timeout in seconds (default: 30)

Returns:

Dict with ‘exitCode’, ‘stdout’, ‘stderr’, ‘durationMs’

Raises:

NoxRunnerHTTPError – If request fails

Return type:

dict

Example

>>> result = client.exec("my-session", ["python3", "--version"])
>>> print(result["stdout"])

exec_shell(session_id, command, workdir='/workspace', env=None, timeout_seconds=30, shell='sh')[source]¶

Execute a shell command string in the sandbox.

This is a convenience method that allows you to pass shell commands as a string (like you would type in a terminal), rather than as a list. The command is executed using sh -c (or bash -c if shell=’bash’).

Parameters:

session_id (str) – Session identifier
command (str) – Shell command string to execute (e.g., “echo hello && ls -la”)
workdir (str) – Working directory (default: ‘/workspace’)
env (Dict[str, str] | None) – Environment variables (optional)
timeout_seconds (int) – Command timeout in seconds (default: 30)
shell (str) – Shell to use (‘sh’ or ‘bash’, default: ‘sh’)

Returns:

Dict with ‘exitCode’, ‘stdout’, ‘stderr’, ‘durationMs’

Raises:

NoxRunnerHTTPError – If request fails
ValueError – If shell is not ‘sh’ or ‘bash’

Return type:

dict

Example

>>> # Simple command
>>> result = client.exec_shell("my-session", "echo hello world")
>>> print(result["stdout"])
hello world

>>> # Command with pipes and redirection
>>> result = client.exec_shell("my-session", "ls -la | head -5")
>>> print(result["stdout"])

>>> # Command with environment variables
>>> result = client.exec_shell(
...     "my-session",
...     "echo $MY_VAR",
...     env={"MY_VAR": "test_value"}
... )
>>> print(result["stdout"])
test_value

>>> # Using bash instead of sh
>>> result = client.exec_shell("my-session", "echo $BASH_VERSION", shell='bash')

health_check()[source]¶

Check if the NoxRunner backend is healthy.

Returns:: True if healthy, False otherwise
Return type:: bool

Example

>>> if client.health_check():
...     print("Backend is healthy")

touch(session_id)[source]¶

Extend the TTL of a sandbox.

Parameters:: session_id (str) – Session identifier
Returns:: True if successful
Raises:: NoxRunnerHTTPError – If request fails
Return type:: bool

Example

>>> client.touch("my-session")
True

upload_files(session_id, files, dest='/workspace')[source]¶

Upload files to the sandbox.

Parameters:

session_id (str) – Session identifier
files (Dict[str, str | bytes]) – Dict mapping file paths to content (str or bytes)
dest (str) – Destination directory (default: ‘/workspace’)

Returns:

True if successful

Raises:

NoxRunnerHTTPError – If request fails

Return type:

bool

Example

>>> client.upload_files("my-session", {
...     "script.py": "print('Hello')",
...     "data.txt": b"binary data"
... })
True

wait_for_pod_ready(session_id, timeout=30, interval=2)[source]¶

Wait for the sandbox execution environment to be ready by polling with a simple command.

Parameters:

session_id (str) – Session identifier
timeout (int) – Maximum time to wait in seconds (default: 30)
interval (int) – Polling interval in seconds (default: 2)

Returns:

True if sandbox is ready, False if timeout

Return type:

bool

Example

>>> if client.wait_for_pod_ready("my-session", timeout=60):
...     print("Sandbox is ready")

exception noxrunner.NoxRunnerError[source]¶

Bases: Exception

Base exception for NoxRunner API errors.

exception noxrunner.NoxRunnerHTTPError(status_code, message, response_body='')[source]¶

Bases: NoxRunnerError

HTTP error from the NoxRunner backend API.

__init__(status_code, message, response_body='')[source]¶

Initialize HTTP error.

Parameters:

status_code (int) – HTTP status code
message (str) – Error message
response_body (str) – Response body (if available)

__str__()[source]¶: String representation of the error.