Skip to content

Commit ac3cd28

Browse files
committed
feat(isolation): implement RFC 0012 isolation backend
Implement the Isolation Backend interface defined by RFC 0012 and migrate the in-pod logic that was coupled to the supervisor behind an in-pod backend. Squashed from the RFC 0012 implementation series (POC + subsequent RFC alignment revisions). Signed-off-by: Jordan Ganoff <jordan.ganoff@docker.com>
1 parent 86dc3f2 commit ac3cd28

31 files changed

Lines changed: 3360 additions & 411 deletions

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ These pipelines connect skills into end-to-end workflows. Individual skill files
3232
| `crates/openshell-cli/` | CLI binary | User-facing command-line interface |
3333
| `crates/openshell-server/` | Gateway server | Control-plane API, sandbox lifecycle, auth boundary |
3434
| `crates/openshell-sandbox/` | Sandbox runtime | Container supervision, policy-enforced egress routing |
35+
| `crates/openshell-isolation/` | Isolation backend contract | RFC 0012 `IsolationBackend` trait + types; the supervisor-facing runtime contract for the boundary |
3536
| `crates/openshell-policy/` | Policy engine | Filesystem, network, process, and inference constraints |
3637
| `crates/openshell-router/` | Privacy router | Privacy-aware LLM routing |
3738
| `crates/openshell-bootstrap/` | Gateway metadata | Gateway registration metadata, auth token storage, mTLS bundle storage |

‎Cargo.lock‎

Lines changed: 19 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎architecture/sandbox.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,22 @@ OpenShell uses overlapping controls rather than a single sandbox primitive:
4949
The supervisor may enrich baseline filesystem allowances for runtime-required
5050
paths, such as proxy support files or GPU device paths when a GPU is present.
5151

52+
## Isolation Backend
53+
54+
The supervisor does not build the boundary inline. It drives an **isolation
55+
backend** (RFC 0012) through one runtime contract (`ensure_boundary` → `bind`
56+
→ `boundary_ready` → `start_agent`), so the same supervisor code runs wherever
57+
the boundary sits. Today only the in-pod backend exists: it builds the boundary
58+
in the same process that operates it, over the existing primitives (network
59+
namespace, proxy, the pre-exec Landlock/seccomp ceiling, procfs identity).
60+
61+
The contract covers the full isolation envelope. `ensure_boundary` establishes
62+
the network namespace; `start_agent` establishes filesystem (Landlock) and
63+
syscall (seccomp) at process entry; `identity` resolves the connecting binary
64+
from procfs at runtime. The lifecycle handles are unforgeable type-state
65+
tokens, so the order (and thus "no workload runs before the boundary is
66+
ready") holds by construction rather than by convention.
67+
5268
## Network and Inference
5369

5470
All ordinary agent egress is routed through the sandbox proxy. The proxy

‎crates/openshell-core/src/sandbox_env.rs‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,17 @@ pub const ENDPOINT: &str = "OPENSHELL_ENDPOINT";
1717
/// Unique identifier of the sandbox being supervised.
1818
pub const SANDBOX_ID: &str = "OPENSHELL_SANDBOX_ID";
1919

20+
/// Serialized RFC 0012 `TopologyDescriptor` for the boundary this sandbox runs
21+
/// behind.
22+
///
23+
/// Set by the compute driver that provisioned the topology; driver-required,
24+
/// so it overrides any user-supplied value. This is the in-pod delivery
25+
/// transport for provisioning's descriptor handoff to the supervisor role.
26+
/// The descriptor is supervisor-only bootstrap state: the supervisor reads it
27+
/// once at startup and never exposes it to the agent, exec sessions, or any
28+
/// other process inside the boundary.
29+
pub const TOPOLOGY_DESCRIPTOR: &str = "OPENSHELL_TOPOLOGY_DESCRIPTOR";
30+
2031
/// Filesystem path to the UNIX socket used for the in-sandbox SSH server.
2132
pub const SSH_SOCKET_PATH: &str = "OPENSHELL_SSH_SOCKET_PATH";
2233

‎crates/openshell-driver-docker/Cargo.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ repository.workspace = true
1212

1313
[dependencies]
1414
openshell-core = { path = "../openshell-core", default-features = false }
15+
openshell-isolation = { path = "../openshell-isolation" }
1516

1617
tokio = { workspace = true }
1718
tonic = { workspace = true }

‎crates/openshell-driver-docker/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,7 @@ overwrites security-critical keys:
136136
- `OPENSHELL_SANDBOX`
137137
- `OPENSHELL_SSH_SOCKET_PATH`
138138
- `OPENSHELL_SANDBOX_COMMAND`
139+
- `OPENSHELL_TOPOLOGY_DESCRIPTOR` (RFC 0012 topology descriptor for the boundary)
139140
- TLS path variables when HTTPS is enabled
140141

141142
Do not allow sandbox images or templates to override these values.

‎crates/openshell-driver-docker/src/lib.rs‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2223,6 +2223,12 @@ fn build_environment_for_oci_user(
22232223
openshell_core::sandbox_env::TELEMETRY_ENABLED.to_string(),
22242224
openshell_core::telemetry::enabled_env_value().to_string(),
22252225
);
2226+
// RFC 0012: the driver provisions the topology and delivers its descriptor
2227+
// to the supervisor through the driver-controlled environment.
2228+
environment.insert(
2229+
openshell_core::sandbox_env::TOPOLOGY_DESCRIPTOR.to_string(),
2230+
openshell_isolation::contract::TopologyDescriptor::in_pod().to_env_value(),
2231+
);
22262232
// The root supervisor executes namespace helpers during bootstrap; keep
22272233
// their search path driver-owned even when the template/spec set PATH.
22282234
environment.insert("PATH".to_string(), SUPERVISOR_PATH.to_string());

‎crates/openshell-driver-kubernetes/Cargo.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ path = "src/main.rs"
1616

1717
[dependencies]
1818
openshell-core = { path = "../openshell-core", default-features = false }
19+
openshell-isolation = { path = "../openshell-isolation" }
1920
openshell-policy = { path = "../openshell-policy" }
2021

2122
tokio = { workspace = true }

‎crates/openshell-driver-kubernetes/src/driver.rs‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2941,6 +2941,13 @@ fn apply_required_env(
29412941
openshell_core::sandbox_env::TELEMETRY_ENABLED,
29422942
openshell_core::telemetry::enabled_env_value(),
29432943
);
2944+
// RFC 0012: the driver provisions the topology and delivers its descriptor
2945+
// to the supervisor through the driver-controlled environment.
2946+
upsert_env(
2947+
env,
2948+
openshell_core::sandbox_env::TOPOLOGY_DESCRIPTOR,
2949+
&openshell_isolation::contract::TopologyDescriptor::in_pod().to_env_value(),
2950+
);
29442951
if !ssh_socket_path.is_empty() {
29452952
upsert_env(
29462953
env,

‎crates/openshell-driver-podman/Cargo.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ path = "src/main.rs"
1616

1717
[dependencies]
1818
openshell-core = { path = "../openshell-core", default-features = false }
19+
openshell-isolation = { path = "../openshell-isolation" }
1920

2021
tokio = { workspace = true }
2122
tonic = { workspace = true, features = ["transport"] }

0 commit comments

Comments
 (0)