Agent isolation layer contracts and open questions

Summary

Each layer has an independent contract, technical dependencies, and residual risks; the architecture remains bounded to a trusted-operator, semi-trusted-agent threat model.

Question and scope

What does each layer change, what remains open, which failure modes are covered, and where are the relevant implementation seams?

Method

This chapter derives constraints from the threat evidence and four-layer model while leaving delivery state to Roadmap.

Findings

Each layer independently narrows a different risk class; the full model composes their contracts.

Docker baseline

macOS ARM → OrbStack Linux VM → Docker daemon → --privileged DinD + role container

Risks:

• DinD --privileged → kernel access to OrbStack VM
• Shared kernel → all sessions share one attack surface
• Credentials in env vars → agent can read raw API keys
• No per-operation access control
• Open network egress

Docker hardening contract

macOS ARM → OrbStack Linux VM → Docker daemon → rootless DinD + role container
                                                  (capability policy, read-only root,
                                                   resource limits, profile reporting)

What changes:

• DinD sidecar moves to rootless mode (no --privileged) or uses minimal capability set
• hardened profile: --cap-drop=ALL + minimal caps, read-only root, resource limits
• Session contract output: operators see exactly what was enforced

What remains:

• Shared OrbStack VM kernel (structural)
• Credentials still in env vars
• No per-operation isolation
• Open egress

See: Docker runtime hardening contract

Per-session VM boundary

macOS ARM → apple/container VM (own kernel, Virtualization.framework)
              → rootless DinD + role container + jackin-capsule

What changes:

• Each jackin❯ session gets its own Linux kernel via Apple's hypervisor
• Kernel exploit in one session cannot reach other sessions or the host
• OrbStack VM no longer in the critical path for session isolation
• Zero install friction on macOS 26 (built into the OS)
• gRPC/vsock attach via vminitd — structured I/O and signal forwarding for TUI sessions

What remains:

• Credentials still in env vars (jackin-exec not yet present)
• No per-operation isolation
• Open egress

Prerequisite: Docker hardening's rootless DinD must validate successfully inside apple/container VMs (specifically: does CAP_SYS_ADMIN work inside apple/container for rootless DinD mount namespaces?). This is an empirical compatibility gate.

See: smolvm backend research (contains the Apple Container comparison and compatibility constraints)

On-demand credential injection

macOS ARM → apple/container VM (own kernel)
              → rootless DinD + role container + jackin-capsule
                → agent calls: jackin-exec ssh sentry
                  → jackin-capsule intercepts
                  → operator approves in TUI (optional)
                  → SSH key resolved from host vault at execution time
                  → command runs with injected key (temp file, /jackin/run/)
                  → output scanned for secret patterns, redacted
                  → sanitized output returned to agent
                  → temp key file deleted

What changes:

• Agent never receives raw credential values in env vars or files
• Operator gets TUI-native approval dialog for sensitive commands
• Workspace secret bindings map command patterns to host-side vaults (op://, env:, file:)
• Output filtering redacts PEM blocks, AWS key patterns, configured regexes

What remains:

• Agent's general tool calls (npm install, etc.) still unconstrained inside container
• Open egress for non-jackin-exec commands

See: Process-level sandboxing (jackin-exec design), Container credential exposure, Host bridge

Process sandboxing and network egress

macOS ARM → apple/container VM (own kernel)
              → rootless DinD + role container + jackin-capsule
                → every agent tool call:
                    → zerobox: filesystem policy (declared mounts only)
                               network policy (declared hosts only)
                               env policy (no leaked secrets)
                    → jackin-exec: credential injection for sensitive commands
                → session-level egress policy: allowlist enforced at VM boundary

What changes:

• Every subprocess wrapped by zerobox: reads/writes only declared mount paths, reaches only declared network hosts, cannot see env vars not explicitly passed
• Session-level network allowlist enforced at VM egress
• Full audit trail: every operation, every allow/deny decision, logged to diagnostics run file

Together these layers address the enumerated failure modes for a trusted operator running semi-trusted agents; the limitations below remain explicit.

See: Process-level sandboxing, Network egress policy

Analysis

The operator cost, engineering scope, and technical dependencies differ by layer.

Threat model

This architecture is designed for jackin❯'s threat model: a trusted operator running semi-trusted AI agents against potentially untrusted external code on a personal macOS ARM machine. It is explicitly NOT designed for:

• Hosted or multi-tenant workloads (strangers' code running on shared infrastructure)
• Enterprise regulatory compliance (HIPAA, PCI-DSS) where third-party audited attestations are required
• Adversarial operators trying to escape the sandbox themselves

For the current threat model, the four layers close the practical failure modes:

Code touchpoints

The key implementation seams for this architecture are:

• crates/jackin-capsule/src/main.rs — PID-1 detection and JACKIN_CAPSULE_FORCE_DAEMON dispatch for Apple Container
• crates/jackin-capsule/src/daemon.rs — daemon control plane and jackin-exec picker dispatch
• crates/jackin-instance/src/manifest.rs — InstanceManifest, DockerResources, and BackendResources with AppleContainerResources
• crates/jackin-runtime/src/runtime/launch.rs — launch orchestration; backend split point
• crates/jackin-docker/src/docker_client.rs — Docker lifecycle boundary; Apple Container gets a peer module
• docker/construct/Dockerfile — role base image; install jackin-exec and zerobox here
• docker/runtime/entrypoint.sh — capsule startup inside role container; inject JACKIN_EXEC_BINDINGS env var
• crates/jackin-config/src/schema.rs — AppConfig + WorkspaceConfig runtime backend fields
• crates/jackin-core/src/env_value.rs — EnvValue::Extended and OpRef.on_demand for jackin-exec

Implications for jackin❯

Keep roadmap delivery state separate from this architecture. Validate compatibility gates empirically and expose active layers and residual risk through the session contract.

Limitations and unknowns

Apple Container compatibility gate

The most critical open question is whether rootless DinD can run inside an apple/container VM:

1. Does apple/container allow --cap-add CAP_SYS_ADMIN? (needed for mount namespaces in rootless DinD)
2. Does rootless DinD pass docker build, Compose, and Testcontainers inside the apple/container VM?
3. Does jackin-capsule run correctly as non-PID-1 (JACKIN_CAPSULE_FORCE_DAEMON=1) with proper SIGTERM propagation, exit-code visibility, and Ctrl+C passthrough?

If rootless DinD fails inside apple/container: smolvm is the fallback (documented Docker-in-VM path exists, though constrained). See smolvm backend research for the full fallback plan.

jackin-exec design decisions

1. Binary name: jackin-exec proposed — needs final decision before baking into construct image (renaming later breaks existing role system prompts and MCP tool descriptions)
2. MCP vs binary vs PATH-shadowing: binary + MCP recommended; PATH-shadowing noted but not recommended (lacks transparency)
3. Approval UX for high-frequency sessions: "Approve All Similar" and "Always for Session" modes need TUI design — see TUI design decisions

Apple Container limitations at the cutoff

Sources

• Threat and platform evidence
• Four-layer model

Related work