doctor

doctor

Container health check protocol and sandbox-level diagnostics.

Defines the shared :class:DoctorCheck / :class:CheckVerdict protocol used across the terok package chain (sandbox → agent → terok). Each package contributes domain-specific checks; the top-level terok sickbay orchestrates execution inside containers via podman exec.

Sandbox-level checks verify host-side service reachability from within a container (credential proxy TCP, SSH agent TCP) and shield firewall state.

CheckVerdict(severity, detail, fixable=False) dataclass

Result of evaluating a single health check probe.

severity instance-attribute

"ok", "warn", or "error".

detail instance-attribute

Human-readable explanation.

fixable = False class-attribute instance-attribute

Whether fix_cmd should be offered to the operator.

DoctorCheck(category, label, probe_cmd, evaluate, fix_cmd=None, fix_description='', host_side=False) dataclass

A single health check to run inside (or against) a container.

The probe_cmd is executed via podman exec <cname> ... by the orchestrator. The evaluate callable interprets the result. If fix_cmd is set, the orchestrator may offer it when the check fails with fixable=True.

Dual execution modes:

• Container mode (host_side=False): the orchestrator runs probe_cmd via podman exec and passes the result to evaluate. The standalone doctor command runs the same probe_cmd directly via subprocess on the host.
• Host-side mode (host_side=True): the orchestrator bypasses probe_cmd entirely and performs the check via Python APIs (e.g. make_shield), then passes resolved state to evaluate. The standalone doctor command calls evaluate(0, "", "") and the function performs the check itself or reports a neutral result.

category instance-attribute

Grouping key: "bridge", "env", "mount", "network", "shield", "git".

label instance-attribute

Human-readable check name shown in output.

probe_cmd instance-attribute

Shell command to run inside the container via podman exec.

evaluate instance-attribute

(returncode, stdout, stderr) → CheckVerdict.

fix_cmd = None class-attribute instance-attribute

Optional remediation command for podman exec.

fix_description = '' class-attribute instance-attribute

Shown to the operator before applying the fix.

host_side = False class-attribute instance-attribute

If True, the check runs on the host (not via podman exec). The orchestrator calls evaluate(0, "", "") and the evaluate function performs the host-side check itself.

sandbox_doctor_checks(*, proxy_port=None, ssh_agent_port=None, desired_shield_state=None)

Return sandbox-level health checks for in-container diagnostics.

Parameters:

Name	Type	Description	Default
proxy_port	int | None	Credential proxy TCP port (skip check if None).	None
ssh_agent_port	int | None	SSH agent TCP port (skip check if None).	None
desired_shield_state	str | None	Expected shield state from shield_desired_state file ("up", "down", "down_all", or None to skip).	None

Returns:

Type	Description
list[DoctorCheck]	List of :class:DoctorCheck instances ready for orchestration.

Source code in src/terok_sandbox/doctor.py

def sandbox_doctor_checks(
    *,
    proxy_port: int | None = None,
    ssh_agent_port: int | None = None,
    desired_shield_state: str | None = None,
) -> list[DoctorCheck]:
    """Return sandbox-level health checks for in-container diagnostics.

    Args:
        proxy_port: Credential proxy TCP port (skip check if ``None``).
        ssh_agent_port: SSH agent TCP port (skip check if ``None``).
        desired_shield_state: Expected shield state from ``shield_desired_state``
            file (``"up"``, ``"down"``, ``"down_all"``, or ``None`` to skip).

    Returns:
        List of :class:`DoctorCheck` instances ready for orchestration.
    """
    checks: list[DoctorCheck] = []
    if proxy_port is not None:
        checks.append(_make_proxy_check(proxy_port))
    if ssh_agent_port is not None:
        checks.append(_make_ssh_agent_check(ssh_agent_port))
    checks.append(_make_shield_check(desired_shield_state))
    return checks