Client API

NoxRunnerClient

class noxrunner.client.NoxRunnerClient(base_url=None, timeout=30, local_test=False)

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)

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)

health_check()

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")

create_sandbox(session_id, ttl_seconds=900, image=None, cpu_limit=None, memory_limit=None, ephemeral_storage_limit=None)

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')}")

touch(session_id)

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

exec(session_id, cmd, workdir='/workspace', env=None, timeout_seconds=30)

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')

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')

upload_files(session_id, files, dest='/workspace')

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

download_files(session_id, src='/workspace')

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')

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

delete_sandbox(session_id)

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

wait_for_pod_ready(session_id, timeout=30, interval=2)

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")