launcher

launcher

How the parent supervisor spawns one child process per service.

Each service runs as its own python -m terok_sandbox supervise-child <service> <container_id> <sidecar_path> process on the parent's own interpreter — -m resolves through terok_sandbox.__main__ whatever the install layout, so a child needs neither terok-sandbox on $PATH nor a rendered wrapper.

Isolation is the child's own job: the instant it starts it hardens itself (harden_self) and labels its own sockets for SELinux, all before it opens the credential store. Nothing about that depends on how the process was spawned, so the launch here is a plain fork-exec. The parent's package search path survives wrapper-based Python installations, but cwd imports remain excluded.

__all__ = ['ChildHandle', 'launch_child'] module-attribute

ChildHandle(service, process) dataclass

A launched child: its service name and the process running it.

service instance-attribute

process instance-attribute

pid property

The child's process id.

launch_child(service, container_id, sidecar_path) async

Fork+exec python -m terok_sandbox supervise-child <service> ….

The parent's one spawn primitive. The child hardens itself and binds its own socket. The environment preserves the parent's package paths; the returned ChildHandle is what the supervisor waits on and, at shutdown, signals.

Source code in src/terok_sandbox/supervisor/launcher.py

async def launch_child(service: str, container_id: str, sidecar_path: Path) -> ChildHandle:
    """Fork+exec ``python -m terok_sandbox supervise-child <service> …``.

    The parent's one spawn primitive.  The child hardens itself and binds
    its own socket. The environment preserves the parent's package paths; the
    returned [`ChildHandle`][terok_sandbox.supervisor.launcher.ChildHandle]
    is what the supervisor waits on and, at shutdown, signals.
    """
    process = await asyncio.create_subprocess_exec(
        sys.executable,
        "-P",
        "-m",
        "terok_sandbox",
        "supervise-child",
        service,
        container_id,
        str(sidecar_path),
        env=child_process_env(),
    )
    return ChildHandle(service=service, process=process)