Module Functions

The nono_py module provides functions for applying sandboxes, starting the network proxy, and checking platform support. It also provides policy-loading helpers for filesystem and network policy resolution.

apply

apply(caps: CapabilitySet) -> None

Apply the sandbox with the given capabilities. This is irreversible. Once called, the current process and all child processes can only access resources granted by the capabilities. There is no way to expand permissions after this call.

CapabilitySet

required

The capability set defining permitted operations.

Raises:

RuntimeError - Platform not supported or sandbox initialization failed

Example

from nono_py import CapabilitySet, AccessMode, apply

caps = CapabilitySet()
caps.allow_path("/tmp", AccessMode.READ_WRITE)
caps.block_network()

# After this call, the process is sandboxed
apply(caps)

# These work:
with open("/tmp/test.txt", "w") as f:
    f.write("Hello")

# These fail with PermissionError:
open("/etc/passwd", "r")

No escape hatch. Once apply() succeeds:

Permissions cannot be expanded
The sandbox persists until process exit
All child processes inherit the same restrictions
There is no “undo” or “disable” function

Error Handling

from nono_py import CapabilitySet, AccessMode, apply, is_supported

caps = CapabilitySet()
caps.allow_path("/tmp", AccessMode.READ_WRITE)

if not is_supported():
    print("Warning: sandboxing not available, running without protection")
else:
    try:
        apply(caps)
        print("Sandbox applied successfully")
    except RuntimeError as e:
        print(f"Failed to apply sandbox: {e}")
        exit(1)

is_supported

is_supported() -> bool

Check if sandboxing is supported on this platform. Returns: True if sandboxing is available.

Example

from nono_py import is_supported

if is_supported():
    print("Sandbox available")
else:
    print("Sandbox not available")

Platform Requirements

Platform	Requirement
Linux	Kernel 5.13+ with Landlock enabled
macOS	macOS 10.5+ (always available)
Windows	Not supported (always returns `False`)

Use support_info() for more detailed information about why sandboxing might not be available.

support_info

support_info() -> SupportInfo

Get detailed information about sandbox support on this platform. Returns: SupportInfo object with platform details.

Example

from nono_py import support_info

info = support_info()

print(f"Platform: {info.platform}")
print(f"Supported: {info.is_supported}")
print(f"Details: {info.details}")

Output examples: macOS:

Platform: macos
Supported: True
Details: Seatbelt sandbox available

Linux with Landlock:

Platform: linux
Supported: True
Details: Landlock ABI v5 available

Linux without Landlock:

Platform: linux
Supported: False
Details: Landlock not available (kernel too old)

Detailed Platform Check

from nono_py import support_info
import sys

def require_sandbox():
    """Exit if sandboxing is not available."""
    info = support_info()

    if info.is_supported:
        return

    print(f"Error: Sandboxing required but not available", file=sys.stderr)
    print(f"Platform: {info.platform}", file=sys.stderr)
    print(f"Details: {info.details}", file=sys.stderr)

    if info.platform == "linux":
        print("\nTo enable Landlock on Linux:", file=sys.stderr)
        print("  1. Upgrade to kernel 5.13 or later", file=sys.stderr)
        print("  2. Ensure CONFIG_SECURITY_LANDLOCK=y in kernel config", file=sys.stderr)

    sys.exit(1)

require_sandbox()

sandboxed_exec

sandboxed_exec(
    caps: CapabilitySet,
    command: list[str],
    cwd: str | None = None,
    timeout_secs: float | None = None,
    env: list[tuple[str, str]] | None = None,
    inherit_env: bool = False,
    max_processes: int | None = None,
) -> ExecResult

Run a command in a sandboxed child process while the Python caller remains unsandboxed. The child receives only the capabilities in caps.

CapabilitySet

required

Capability set defining the child’s permitted filesystem and network access.

list[str]

required

Program and arguments to execute, for example ["python", "agent.py"].

str | None

Working directory for the child process.

float | None

Maximum runtime in seconds. On timeout, sandboxed_exec() kills the sandboxed command’s process group and returns exit code 124.

list[tuple[str, str]] | None

Explicit child environment variables. The parent environment is not inherited unless inherit_env=True.

bool

If true, inherit the parent environment and apply env as overrides. Dynamic-loader environment variables such as LD_* and DYLD_* are rejected.

int | None

Optional RLIMIT_NPROC value for the child. This is a per-real-UID kernel limit, not a per-sandbox process-tree limit.

Returns: ExecResult with stdout, stderr, and exit_code. Raises:

RuntimeError - Fork failed, sandbox setup failed, or command could not be executed
ValueError - Command is empty, timeout is negative, or max_processes is zero

Example

from nono_py import AccessMode, CapabilitySet, sandboxed_exec

caps = CapabilitySet()
caps.allow_path("/workspace", AccessMode.READ_WRITE)
caps.block_network()

result = sandboxed_exec(
    caps,
    ["python", "agent.py"],
    cwd="/workspace",
    timeout_secs=30.0,
)
print(result.exit_code, result.stdout)

Optional Process Limit

max_processes sets RLIMIT_NPROC before exec. Use it only when sandboxed executions run under a dedicated Unix UID. The kernel counts every process already owned by that UID, so on a normal shared user account a small value can make the sandboxed program’s first fork() fail with EAGAIN instead of providing a per-sandbox process budget.

# Dedicated sandbox UID/container only.
result = sandboxed_exec(
    caps,
    ["python", "agent.py"],
    cwd="/workspace",
    timeout_secs=30.0,
    max_processes=64,
)

Use cgroup pids.max, containers, or microVMs for reliable per-execution fork limits.

start_proxy

start_proxy(config: ProxyConfig) -> ProxyHandle

Start the nono network filtering proxy. Creates a localhost proxy server that provides domain filtering, credential injection, and audit logging for sandboxed child processes. The proxy runs on a background thread and is shut down via the returned handle.

ProxyConfig

required

Proxy configuration including allowed hosts, credential routes, and bind settings.

Returns: ProxyHandle with env_vars(), credential_env_vars(), drain_audit_events(), and shutdown(). Raises:

RuntimeError - Proxy failed to start (port in use, etc.)

Example

from nono_py import ProxyConfig, RouteConfig, start_proxy, sandboxed_exec

config = ProxyConfig(
    allowed_hosts=["api.openai.com"],
    routes=[
        RouteConfig(
            prefix="/openai",
            upstream="https://api.openai.com",
            credential_key="openai-key",
        ),
    ],
)
proxy = start_proxy(config)

# Inject env vars into sandboxed child
env = list(proxy.env_vars().items()) + list(proxy.credential_env_vars().items())
result = sandboxed_exec(caps, ["python", "agent.py"], env=env)
# Optional for dedicated sandbox UIDs only:
# result = sandboxed_exec(caps, ["python", "agent.py"], env=env, max_processes=64)

# Collect audit trail and shut down
events = proxy.drain_audit_events()
proxy.shutdown()

embedded_policy_json

embedded_policy_json() -> str

Return the bundled policy JSON document as a raw string. Returns: JSON text for the embedded policy.

Example

from nono_py import embedded_policy_json

raw = embedded_policy_json()
print(raw[:80])

load_policy

load_policy(json: str) -> Policy

Parse a policy JSON document into a Policy object. Returns: Policy with group inspection and resolution helpers. Raises:

ValueError - Invalid policy JSON, including unknown policy fields

Example

from nono_py import load_policy

policy = load_policy(
    """
    {
      "groups": {
        "offline": {
          "description": "Disable outbound network",
          "network": { "block": true }
        },
        "proxy_web": {
          "description": "Allow only example.com through the proxy",
          "network": { "allow_proxy": ["example.com"] }
        }
      }
    }
    """
)

print(policy.group_names())
proxy_config = policy.resolve_proxy_config(["proxy_web"])
print(proxy_config.allowed_hosts if proxy_config else [])

Policy.resolve_proxy_config() follows the same network field naming used by the main nono profile format:

Canonical key: network.allow_domain
Accepted aliases: network.allow_proxy, network.proxy_allow

If multiple groups specify different upstream_proxy / external_proxy values, resolution fails with ValueError instead of silently overwriting the earlier proxy. Policy JSON is parsed strictly. Unknown fields are rejected instead of being ignored. When resolving groups with proxy-filtered network policy, resolve_groups() fails closed by blocking direct network access. After starting the proxy, call caps.proxy_only(proxy) and pass proxy.sandbox_env() to sandboxed_exec().

load_embedded_policy

load_embedded_policy() -> Policy

Parse the bundled policy JSON and return it as a Policy.

Example

from nono_py import load_embedded_policy

policy = load_embedded_policy()
print("deny_credentials" in policy.group_names())

Import

All functions are available from the top-level module:

from nono_py import (
    apply,
    embedded_policy_json,
    is_supported,
    load_embedded_policy,
    load_policy,
    sandboxed_exec,
    start_proxy,
    support_info,
)

CapabilitySet - Build capabilities to pass to apply()
ProxyConfig - Configure the network proxy
SnapshotManager - Filesystem snapshots and rollback
SupportInfo - Returned by support_info()
QueryContext - Check permissions without applying

Getting Started

API Reference

Examples

apply

Example

Error Handling

is_supported

Example

Platform Requirements

support_info

Example

Detailed Platform Check

sandboxed_exec

Example

Optional Process Limit

start_proxy

Example

embedded_policy_json

Example

load_policy

Example

load_embedded_policy

Example

Import

​apply

​Example

​Error Handling

​is_supported

​Example

​Platform Requirements

​support_info

​Example

​Detailed Platform Check

​sandboxed_exec

​Example

​Optional Process Limit

​start_proxy

​Example

​embedded_policy_json

​Example

​load_policy

​Example

​load_embedded_policy

​Example

​Import

​Related

apply

Example

Error Handling

is_supported

Example

Platform Requirements

support_info

Example

Detailed Platform Check

sandboxed_exec

Example

Optional Process Limit

start_proxy

Example

embedded_policy_json

Example

load_policy

Example

load_embedded_policy

Example

Import

Related