InternetSettings

InternetSettings controls outbound network access for supported private sandbox networks. Open access remains the default.

Import

from celesto import InternetSettings

Fields

"open" | "off" | "restricted" | None

default:"None"

Outbound access mode. open allows internet access, off blocks outbound access, and restricted allows only allowed_cidrs. Leave unset when using allowed_domains.

tuple[str, ...]

default:"()"

IPv4 addresses and network ranges allowed in restricted mode. A bare address is stored as a /32 range. Overlapping ranges are combined.

tuple[str, ...]

default:"(\"*\",)"

Domains resolved to IPv4 addresses during sandbox setup. URL entries are reduced to their hostname. Do not combine this field with mode.

tuple[str, ...]

default:"(\"*\",)"

Reserved field. HTTP-method filtering is not supported, so only the default wildcard is accepted.

Input lists are accepted for collection fields. Stored settings are immutable tuples, while saved JSON uses arrays.

Turn outbound access off

from celesto import InternetSettings, Celesto

with Celesto(
    backend="qemu",
    internet_settings=InternetSettings(mode="off"),
) as vm:
    print(vm.run("echo hello").stdout)

QEMU supports off mode with its default network on macOS and Linux.

Allow IPv4 destinations

from pathlib import Path
from celesto import InternetSettings, Celesto, VMConfig

config = VMConfig(
    kernel_path=Path("/path/to/vmlinux"),
    rootfs_path=Path("/path/to/rootfs.ext4"),
    backend="qemu",
    qemu_network="tap",
    internet_settings=InternetSettings(
        mode="restricted",
        allowed_cidrs=["203.0.113.10", "198.51.100.0/24"],
    ),
)

with Celesto(config=config) as vm:
    print(vm.run("echo ready").stdout)

QEMU restricted mode requires explicit TAP networking on Linux. Firecracker restrictions require Linux and the vsock command channel. See Network controls for the support matrix and higher-level examples.

Validation

restricted requires at least one entry in allowed_cidrs.
allowed_cidrs can only be used with restricted.
IPv6 ranges, sandbox ranges, and link-local ranges are rejected.
allowed_domains cannot be combined with mode.
HTTP-method restrictions are rejected.
Unknown fields are rejected.

Direct InternetSettings and VMConfig construction raises Pydantic’s ValidationError. Public Celesto creation methods raise celesto.ValidationError for invalid or unsupported combinations.

Celesto CLI

Celesto API

Celesto CLI

Agentor API

Import

Fields

Turn outbound access off

Allow IPv4 destinations

Validation

​Import

​Fields

​Turn outbound access off

​Allow IPv4 destinations

​Validation

​Related

Import

Fields

Turn outbound access off

Allow IPv4 destinations

Validation

Related