Backend API

SandboxBackend (Abstract Base Class)

class noxrunner.backend.base.SandboxBackend

Bases: ABC

Abstract base class for sandbox execution backends.

All backends (local, HTTP, k8s, docker, etc.) must implement this interface. This provides a unified API regardless of the underlying implementation.

abstractmethod health_check()

Check if the backend is healthy.

Returns:

True if healthy, False otherwise

Return type:

bool

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

Create or ensure a sandbox 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’

Return type:

dict

abstractmethod touch(session_id)

Extend the TTL of a sandbox.

Parameters:

session_id (str) – Session identifier

Returns:

True if successful

Return type:

bool

abstractmethod 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’

Return type:

dict

abstractmethod 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

Return type:

bool

abstractmethod 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

Return type:

bytes

abstractmethod delete_sandbox(session_id)

Delete a sandbox.

Parameters:

session_id (str) – Session identifier

Returns:

True if successful

Return type:

bool

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

Wait for sandbox to be ready.

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

HTTPSandboxBackend

HTTP client backend for remote NoxRunner services.

class noxrunner.backend.http.HTTPSandboxBackend(base_url, timeout=30)

Bases: SandboxBackend

HTTP client backend for NoxRunner sandbox execution.

This backend communicates with a remote NoxRunner-compatible API via HTTP. The remote service may be implemented using Kubernetes, Docker, or other technologies.

This backend acts as an HTTP client and does not implement the sandbox itself. It connects to a remote service that provides the actual sandbox implementation.

__init__(base_url, timeout=30)

Initialize the HTTP backend.

Parameters:

• base_url (str) – Base URL of the NoxRunner backend (e.g., “http://127.0.0.1:8080”)

• timeout (int) – Request timeout in seconds (default: 30)

health_check()

Check if the 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 exists.

touch(session_id)

Extend the TTL of a sandbox.

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

Execute a command in the sandbox.

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

Upload files to the sandbox.

download_files(session_id, src='/workspace')

Download files from the sandbox as a tar archive.

delete_sandbox(session_id)

Delete a sandbox.

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

Wait for sandbox to be ready.

LocalBackend

Local filesystem backend for development and testing.

class noxrunner.backend.local.LocalBackend(base_dir='/tmp')

Bases: SandboxBackend

Local filesystem backend for offline testing.

WARNING: This backend executes commands in the local environment using temporary directories. It should ONLY be used for testing purposes. Using this in production can cause severe data loss or security risks.

__init__(base_dir='/tmp')

Initialize local sandbox backend.

Parameters:

base_dir (str) – Base directory for sandbox storage (default: /tmp)

health_check()

Check if the local sandbox 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 exists.

Parameters:

• session_id (str) – Unique session identifier

• ttl_seconds (int) – Time to live in seconds

• image (str | None) – Container image (ignored in local mode)

• cpu_limit (str | None) – CPU limit (ignored in local mode)

• memory_limit (str | None) – Memory limit (ignored in local mode)

• ephemeral_storage_limit (str | None) – Storage limit (ignored in local mode)

Returns:

Dict with ‘podName’ and ‘expiresAt’

Return type:

dict

touch(session_id)

Extend the TTL of a sandbox.

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

Execute a command in the sandbox.

WARNING: This executes commands in the local environment!

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

Upload files to the sandbox.

download_files(session_id, src='/workspace')

Download files from the sandbox as a tar archive.

delete_sandbox(session_id)

Delete a sandbox.

This removes the entire /tmp/{sandbox_id} directory.

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

Wait for sandbox to be ready.

Internal Modules

Security Module

Command validation for sandbox security.

This module provides command validation to prevent dangerous operations in sandbox environments.

class noxrunner.security.command_validator.CommandValidator

Bases: object

Validates commands for safety in sandbox environments.

This validator checks commands against allowlists and blocklists to prevent dangerous operations.

ALLOWED_COMMANDS = {'[', 'awk', 'bash', 'cat', 'cmp', 'cp', 'cut', 'diff', 'echo', 'env', 'false', 'file', 'find', 'grep', 'gunzip', 'gzip', 'head', 'ln', 'ls', 'mkdir', 'mv', 'node', 'printenv', 'pwd', 'python', 'python2', 'python3', 'readlink', 'sed', 'sh', 'sort', 'stat', 'tail', 'tar', 'test', 'touch', 'tr', 'true', 'type', 'uniq', 'unzip', 'wc', 'which', 'xargs', 'zip', 'zsh'}

BLOCKED_COMMANDS = {'chgrp', 'chmod', 'chown', 'dd', 'del', 'fdisk', 'format', 'halt', 'init', 'killall', 'mkfs', 'mount', 'poweroff', 'reboot', 'rm', 'rmdir', 'shutdown', 'su', 'sudo', 'umount', 'unlink'}

validate(cmd)

Validate that command is safe to execute.

Parameters:

cmd (List[str]) – Command to validate (list of strings)

Returns:

True if command is safe, False otherwise

Return type:

bool

is_allowed(command)

Check if a command is in the allowed list.

Parameters:

command (str) – Command name to check

Returns:

True if command is allowed

Return type:

bool

is_blocked(command)

Check if a command is in the blocked list.

Parameters:

command (str) – Command name to check

Returns:

True if command is blocked

Return type:

bool

Path sanitization for sandbox security.

This module provides path sanitization to prevent path traversal attacks in sandbox environments.

class noxrunner.security.path_sanitizer.PathSanitizer

Bases: object

Sanitizes paths to ensure they’re within the sandbox.

Security: Prevents path traversal attacks by ensuring all paths are within the sandbox directory.

sanitize(path, sandbox_path, workspace_name='workspace')

Sanitize a path to ensure it’s within the sandbox.

Parameters:

• path (str) – Path to sanitize (can be absolute or relative)

• sandbox_path (Path) – Base sandbox directory path

• workspace_name (str) – Name of the workspace directory (default: “workspace”)

Returns:

Sanitized Path object that is guaranteed to be within sandbox

Return type:

Path

Security:

• Prevents path traversal attacks (../)

• Redirects paths outside sandbox to workspace root

• Handles both absolute and relative paths

ensure_within_sandbox(path, sandbox_path)

Check if a path is within the sandbox.

Parameters:

• path (Path) – Path to check

• sandbox_path (Path) – Base sandbox directory path

Returns:

True if path is within sandbox, False otherwise

Return type:

bool

sanitize_filename(filename)

Sanitize a filename to prevent path traversal.

Parameters:

filename (str) – Filename to sanitize

Returns:

Sanitized filename (only the basename, no path components)

Return type:

str

File Operations Module

Tar archive handling utilities.

This module provides utilities for creating and extracting tar archives used in file synchronization between local and sandbox environments.

class noxrunner.fileops.tar_handler.TarHandler

Bases: object

Handles tar archive creation and extraction.

This class provides methods to create tar archives from file dictionaries and extract tar archives to directories, with security checks.

create_tar(files)

Create a tar archive from a dictionary of files.

Parameters:

files (Dict[str, str | bytes]) – Dictionary mapping file paths to content (str or bytes)

Returns:

Tar archive as bytes (gzip compressed)

Return type:

bytes

create_tar_from_directory(directory, src)

Create a tar archive from a directory.

Parameters:

• directory (Path) – Directory to archive

• src (Path) – Source path (for relative path calculation)

Returns:

Tar archive as bytes (gzip compressed)

Return type:

bytes

extract_tar(tar_data, dest, sandbox_path=None, allow_absolute=False)

Extract a tar archive to a directory.

Parameters:

• tar_data (bytes) – Tar archive data (bytes)

• dest (Path) – Destination directory

• sandbox_path (Path | None) – Optional sandbox path for security checks

• allow_absolute (bool) – Whether to allow absolute paths (default: False)

Returns:

Number of files extracted

Return type:

int