Containment

How smith contains the processes it starts, systemd units on Linux and job objects on Windows, the uncontained development profile, checks_require_containment and run_query host

This page says how runtime and check processes are sealed off. File:line citations are in parentheses; "not checked" means the code read for this page does not settle it. Nothing here was run on a live host.

01profiles and limits#

A process is admitted under an execution profile. Two exist: local_subscription, the default, and uncontained_development. Any other name is refused as unknown_profile.

Unset limits take these defaults:

Memory and process limits come from the profile policy. Their default values: not checked. Admission refuses a limit that is not positive once defaults are applied, as invalid_limits.

02Linux#

On Linux a contained process is started in a transient systemd user unit with systemd-run --user. Smith needs systemd-run, env and systemctl on PATH, and refuses with "no admitted containment mechanism" if the admission is not the systemd mechanism. The cgroup v2 requirement is stated at; how the probe checks for it: not checked.

• Each process gets a unit named smith-runtime-<pid>-<n>.service, where <pid> is smith's own pid and <n> counts up.
• The unit is BindsTo and After an owner unit, smith-controller-<pid>.service. That owner unit is itself created with MemoryMax of 16 MiB, TasksMax of 4 and CPUQuota of 10 percent.
• Memory: MemoryMax is the memory limit, MemorySwapMax=0 keeps it off swap, and OOMPolicy=kill.
• Processes: TasksMax is the process limit.
• Cpu: CPUQuota is the cpu quota percent.
• Deadline: RuntimeMaxSec is the timeout, and TimeoutStopSec the termination grace.
• KillMode=control-group stops every process in the unit.
• A contained unit can be isolated from the network and home. Whether a host can do that is probed once per process. When it cannot, checks run contained but not isolated: not checked beyond that.

03Windows#

On Windows the processes are put in a job object (internal/host/windowsjob/job_windows.go). A contained profile is admitted only after a job carrying every limit was created and read back; otherwise it is refused as mechanism_unavailable. The cpu quota becomes a hard-cap job rate. More is on windows.

04the uncontained development profile#

uncontained_development runs the process directly, with no containment mechanism and Enforced: false. It is admitted only when the caller grants it: without AllowUncontainedDev it is refused as authority_required with "the conductor did not grant uncontained development execution". The grant is the allow_uncontained_development input of the run tools. A process request under this profile is launched direct.

The limits are still validated but are not enforced by a host. Whether the runtime adapters enforce them in another way: not checked.

05checks_require_containment#

By default checks run uncontained on a host that cannot contain them, and the core logs that. With checks_require_containment set, every command check is refused before launch when the host cannot contain it, with the message "command check containment: the host can't contain checks () and checks_require_containment is set". On Windows and the macOS process-group host this refuses every check, because only resource limits apply there. See checks.

06node checks#

A contained check has no home and no network, so a node project needs its npm cache and toolchain handed in. The cache is NPM_CONFIG_CACHE from smith's own environment, else npm_config_cache, else ~/.npm if that directory exists. When found it is set in the check's environment as NPM_CONFIG_CACHE and bound read-only (checkIsolationPaths); when the host has none, neither happens. Smith never adds --offline or --cache: that stays the check's own choice.

An executable that resolves under $HOME (such as ~/.nvm/versions/node/vX/bin/npm) has its toolchain directory (~/.nvm/versions/node/vX) bound read-only for that check alone (checkToolchainPaths). It is not put on PATH.

If npm fails with ENOTCACHED the run stops as environment-broken, not as a work failure, with " is not in the npm cache; add it on the host and relaunch" (checkEnvironmentBroken). See checks.

07run_query host#

run_query with host returns the host rows of one run, read from the run store. It is refused with "host is not available from this run store" when the store cannot give them. On Linux the rows are the systemd units of the run (runs). The row fields: not checked.

An orphaned unit shows up as a smith-runtime-* unit in systemctl --user list-units 'smith-runtime-*' (internal/capability/mcpserver/testdata/find-places.yaml:33).