Adopt BoundaryKit's governance pattern

BoundaryKit is a documentation-first framework informed by experience operating a local agent-sandbox implementation. It helps others decide where an untrusted, tool-wielding agent may run, what it may do, and what evidence supports each security claim. OpenShell and Ansible are used in the local implementation, but the method requires neither. Use mechanisms you can inspect and test; begin your own adoption with a bounded, synthetic workload.

Read path: this guide → filled fictional adoption packet → architecture and trust model → operational case study. The verification model separates running-system status from individual test results. NOT RUN in the fictional packet describes its teaching probes, not the operator's running local system.

Packet and gate rules

Keep one adoption packet per workload. Its five named outputs are a Boundary record, Capability contract, Placement decision, Desired-state record, and Recovery rehearsal record. Each output identifies its workload, revision, reviewer, date, and evidence level. A reviewer can complete the paper/design checks below without deploying anything; mark runtime checks not run, never PASS, until the target implementation is observed. An unmet or unobserved runtime check blocks a runtime or promotion claim. Record failures with their observed behavior, scope, and rollback decision instead of silently broadening access.

Before each test, name the exact boundary and expected refusal/success; collect only minimum, non-secret observations in an appropriately private evidence store. An agent prompt or tool description is not authorization. A change in workload, permissions, policy, runtime, or provider route reopens affected gates. A public summary is newly written from cleared lessons, not copied from private receipts; follow the public/private boundary and declassification checklist.

1. Map trust boundaries

Inputs: the task and data classification; who requests/approves it; inputs from users, retrieval, tools, and models; assets the agent could reach; proposed execution and administration surfaces.

Steps:

1. Identify the untrusted agent, its input/data flows, intended output, and the authority that approves consequential actions. Draw separate operator/control, execution, data, secret, provider, and audit zones; a zone is a model until a mechanism enforces its boundary.
2. For every crossing, record source → destination, identity, allowed operation, denying mechanism, and what observation could falsify the claim. Include read-only and denied crossings, not just intended success paths.
3. State a bounded initial risk tier and non-claims. Treat retrieved text, tool responses, and model output as data, not policy. Place human approval before writes or outward disclosure.

Output — Boundary record: workload scope, zone map, crossing matrix, asset owners, approval actor, risk tier, and explicit non-claims.

Pass/fail acceptance: design PASS only if every input and output maps to a zone and every crossing has a named allow/deny authority and proposed observation; otherwise FAIL. Runtime PASS for a crossing only when its authorized path and at least one attempted unauthorized path are observed at that specific enforcement point with identity and scope recorded. A diagram, policy file, or test of a neighboring layer does not pass it. Unrun probes are NOT RUN.

2. Select the smallest tool surface

Inputs: Boundary record, task outcomes, available tools with schemas and effects, data classification, provider/egress needs, and approval owner.

Steps:

1. List each required operation and select only the tool and method that performs it; record schema identity/version, exact read/write effect, resource scope, and reason. Prefer no tool where task output can be produced without one.
2. Define a deny-by-default discovery/invocation contract for every other and unknown tool. Treat tool names, descriptions, arguments, responses, and retrieved documents as untrusted data. Bind outbound destinations to the approved operation, not an unrestricted network grant.
3. Place high-impact or external writes behind a human decision before execution. Define the audit event (actor, policy revision, tool, resource class, decision, outcome) without secret values or private payloads. Define how provider credentials remain outside agent-visible material.

Output — Capability contract: allowlist and scopes, denied/unknown behavior, approval path, egress and credential custody, and negative/positive probe matrix.

Pass/fail acceptance: design PASS only if each allowed tool has a task justification, schema identity, scope, and approval rule, and denied/unknown cases have a recorded expected refusal; otherwise FAIL. Runtime PASS only if allowed calls work within scope while denied/unknown tools cannot be discovered or invoked, out-of-scope arguments and destinations are refused, and audit excludes secrets. Any permissive fallback or untested required row is FAIL or NOT RUN, never inferred PASS.

3. Decide grouping and enforced isolation separately

Inputs: Boundary record, Capability contract, workload/data owners, concurrency and failure-domain needs, runtime isolation candidates, and operational constraints.

Steps:

1. Choose logical groupings for ownership, policy administration, and lifecycle. Label them groupings even if a product calls them realms, projects, or tenants; grouping alone does not contain processes, files, network, or secrets.
2. Compare shared process, sandbox/container, VM, and separate host against data sensitivity, kernel/host exposure, boundary independence, recovery cost, and available negative-test access. Document the chosen execution boundary, adjacent workloads, shared components, residual risk, and rejected alternatives.
3. Identify the actual enforcement mechanisms for filesystem, process/privilege, network/egress, tool access, and credential exposure. Plan negative probes from inside the workload plus tests for lateral/neighbor access where isolation is claimed. Do not claim host, VM, inter-group, or provider containment from a sandbox-only observation.

Output — Placement decision: group membership and rationale separate from sandbox/VM/host placement, enforcement ownership, tradeoffs, residual risks, and boundary-specific probes.

Pass/fail acceptance: design PASS only if grouping and execution boundary are separate fields, at least one alternative and its tradeoff are recorded, and every claimed isolation property has a mechanism and matching probe; otherwise FAIL. Runtime PASS only for each precisely named boundary whose negative probes refuse crossing while authorized access works. An absent probe, shared boundary with no independent enforcement, or neighboring-layer result leaves that isolation claim NOT RUN/FAIL.

4. Make configuration reproducible without exporting secrets

Inputs: three prior outputs, approved configuration owner, versioned artifact/policy sources, secret-custody service, and rollback target.

Steps:

1. Describe desired workload, policy, identity, tool schema, egress, group, sandbox, and audit settings in reviewable, versioned configuration. Pin immutable artifact identity and policy revision; record the renderer/apply owner and target. Ansible, another config-as-code system, or a reviewed manual process can realize the same contract.
2. Keep secret references in desired state; resolve values only at the trusted boundary and only for the approved use. Define rotation, revocation, logging redaction, and which identity may fetch a value. No raw value belongs in the packet, agent workspace, image, diff, or public receipt.
3. Compare desired and observed state before change, capture the previous known-good revision, review a dry run/diff, seek authorization for apply, then observe convergence and drift. Record exactly which operations were not executed.

Output — Desired-state record: revision and artifact identity, reviewer/approver, configuration mapping, secret custody, preflight/diff, target, rollback reference, and observed drift/convergence status.

Pass/fail acceptance: design PASS only if every stage-1/2/3 decision maps to a versioned setting or a named manual control, with secret ownership and rollback target; otherwise FAIL. Runtime PASS only after an approved apply and readback match the reviewed revision, unauthorized drift is detected, and agent-visible/logged material lacks secret values. Dry-run success alone is not convergence; without apply/readback, mark NOT RUN.

5. Rehearse failure and recovery before promotion

Inputs: Desired-state record, known-good version, failure hypotheses, backup/restore authority, service objectives, and private evidence destination.

Steps:

1. Choose a safe, authorized test environment and name triggers such as policy-load failure, lost sandbox, revoked credential, misrouted provider, or bad config. Specify expected denial and restoration observations before attempting them. Record baseline authorized and denied checks.
2. Obtain the required operational approval, simulate one failure at a time, confirm fail-closed behavior, restore from the recorded known-good state, and rerun the same boundary, tool, credential, egress, audit, and workload checks. Record timestamps against declared objectives; do not make up a recovery time.
3. Review receipts and unresolved failures. Promote only the measured workload/scope after canary, authorization, egress, audit, recovery/rollback, and service-objective evidence are all present. Keep a stop/rollback decision for a failed check; publication or production traffic is a separate gate.

Output — Recovery rehearsal record: approved test scope, trigger, baseline, expected and actual observations, restore target, before/after checks, timing, reviewer decision, and remaining non-claims.

Pass/fail acceptance: design PASS only if each trigger has an expected fail-closed result, restoration path, owner, and repeated check list; otherwise FAIL. Runtime PASS for a rehearsal only if observed failure, refusal, restoration, and repeated authorized/denied checks match the predeclared expectations and timing objective. A backup file, unexecuted checklist, or configuration-as-code claim is NOT RUN, not recovery proof. Any unmet objective blocks promotion pending remediation and a new rehearsal.

What to claim

A complete packet can truthfully say design reviewed. It cannot say isolation verified, recovery proven, or production-ready until the corresponding runtime receipts exist for the named workload and version. Vendor-specific implementations may be referenced as examples after their actual enforcement and evidence are mapped to this contract. See the worked example for filled decisions with explicitly unexecuted runtime rows.