Skip to navigation
Extensibility

Isolation Backends

View as Markdown

The supervisor uses the IsolationBackend RPC service to discover and bind an isolation backend, then uses the Sandbox Protocol to launch and control the agent workload. The built-in openshell-sandbox runtime and external backends implement the same services, allowing different isolation mechanisms without changing the gateway API or policy model.

The supervisor uses its OpenShellRuntimeBackend client to communicate with the workload-side openshell-sandbox runtime over the Sandbox Protocol.

The protocols

The services are defined in isolation_backend.proto and sandbox_protocol.proto. The supervisor’s concrete RPC client, OpenShellRuntimeBackend, lives in openshell-sandbox-backend.

RPCWhat it does
IsolationBackend.DescribeNegotiates the protocol and capabilities.
IsolationBackend.OpenBoundaryBinds a provisioned resource to an authenticated launch.
IsolationBackend.SuspendBoundary / ResumeBoundaryOptionally retains and restores workload state.
SandboxProtocol.ExchangeCarries admission, process control and I/O, TCP decisions, and relay data.
SandboxProtocol.MediateCarries the DNS mediation handshake, queries, and responses.

The admission sequence is Attach, Confirm, then StartAgent. No workload code runs before StartAgent.

External compute drivers advertise openshell.compute.isolation-backend to accept an operator-selected IsolationBackendRegistration, including its Unix, TCP, or vsock endpoint. The driver provisions the resource and delivers the backend’s trusted launch metadata to the supervisor.

Who Owns What

ComponentOwns
SupervisorPolicy decisions. Policy, credentials, DNS resolution, and approved external connections stay outside the agent workload.
Compute driverPlacement and fencing. The driver creates runtime resources, installs the outer egress fence, and supplies a verified descriptor.
Isolation backendEnforcement. The backend implements the RPC contracts and enforces the admitted policy inside its provisioned resource.

For how openshell-sandbox enforces the boundary, refer to Inside the Sandbox Boundary. For driver-specific workload behavior, refer to Runtimes.