You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 9f08093
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: architecture/compute-runtimes.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -228,7 +228,7 @@ delete, reconciliation removes the row; otherwise it can remain `Deleting`.
228
228
229
229
| Runtime | Best fit | Sandbox boundary | Notes |
230
230
|---|---|---|---|
231
-
| Docker | Local development with Docker available. |Container plus nested sandbox namespace. | Uses host networking so loopback gateway endpoints work from the supervisor. Advertises the combined-supervisor policy-DNS and transparent-TCP substrate. |
231
+
| Docker | Local Linux development with Docker available. |Network-disabled workload container plus native host supervisor. | Uses RFC 0012 supervisor-owned creation and OCI seccomp notification to carry policyDNS and transparentTCP without a proxy port or an OpenShell binary in the workload. |
232
232
| Podman | Rootless or single-machine deployments. | Container plus nested sandbox namespace. | Uses the Podman REST API and CDI GPU devices when available. Delivers the supervisor via OCI image volume by default; falls back to extracting the binary to a host-side cache and bind-mounting it when `userns` is configured (overlay does not support idmapped mounts). Advertises the combined-supervisor policy-DNS and transparent-TCP substrate. |
233
233
| Kubernetes | Cluster deployment through Helm. | Pod plus nested sandbox namespace. | Uses Kubernetes API objects, service accounts, secrets, PVC-backed workspace storage, and GPU resources. |
234
234
| VM | Experimental microVM isolation. | Per-sandbox libkrun VM. | Managed endpoint-backed driver. The gateway spawns `openshell-driver-vm`, waits for its Unix socket, and then consumes it through the same remote `compute_driver.proto` path used by unmanaged endpoint drivers. The VM driver boots a cached bootstrap `rootfs.ext4`, prepares requested OCI images inside a bootstrap VM with `umoci`, attaches the prepared image disk read-only, and gives each sandbox a writable `overlay.ext4` for merged-root changes and runtime material. The driver persists each accepted launch request beside the overlay and restarts those VMs on driver startup without recreating the overlay. |
through the Docker seccomp profile. runc sends the listener FD directly to the
41
+
host supervisor with `SCM_RIGHTS` before the workload starts. The container
42
+
drops every Linux capability and has direct networking disabled.
65
43
66
-
## Stop and Start
67
-
68
-
Stop stops the managed container without removing it. Docker retains the
69
-
container writable layer, attached volumes, labels, token material, and restart
70
-
policy. Start starts that same container, so files in the resolved OCI
71
-
workspace remain available. A durably stopped sandbox is excluded from
72
-
gateway startup recovery and stays stopped across gateway restarts. Delete
73
-
continues to force-remove the container and clean up driver-owned material.
74
-
Graceful gateway shutdown sends `StopSandbox` for each sandbox whose persisted
75
-
phase requires running compute without changing that persisted intent. On
76
-
startup, the gateway sends an idempotent `StartSandbox` request for the same
77
-
sandboxes, restarting their retained containers. Explicitly stopped sandboxes
78
-
remain excluded.
79
-
80
-
Before creating the container, the driver inspects the final sandbox image and
81
-
captures its immutable image ID, raw OCI `Config.User`, and OCI
82
-
`Config.WorkingDir`. Container creation uses that image ID, preventing a
83
-
mutable tag from changing between inspection and launch. The supervisor runs as
84
-
root, resolves omitted policy identity fields from the image declaration, and
85
-
drops only agent children to the resulting identity. Named OCI components
86
-
remain names after validation; a missing group is filled with the user's
87
-
numeric primary GID. Explicit `process.run_as_user` and
88
-
`process.run_as_group` values take precedence independently.
89
-
90
-
An absolute OCI working directory becomes the agent workspace. An empty,
91
-
root (`/`), or explicit `/sandbox` declaration uses `/sandbox`, which OpenShell
92
-
creates when necessary and owns as a compatibility workspace. Any other image
93
-
workdir must already exist without symlink components. The completed identity,
94
-
including supplementary groups, must already be able to traverse every parent
95
-
and write and enter the workdir. OpenShell does not change its ownership or
96
-
mode.
97
-
98
-
OpenShell deliberately asks the Linux kernel to make this access decision
99
-
under the completed sandbox identity instead of reproducing permission rules
100
-
from ownership and mode bits. Mode-bit inspection alone can reject authority
101
-
granted by a POSIX ACL or overlook a denial imposed by a Linux Security Module
102
-
such as SELinux or AppArmor. OpenShell does not configure or otherwise manage
103
-
ACLs or LSM policy here; the one-shot validator only observes the kernel's
104
-
effective decision. This keeps the no-authority-expansion invariant aligned
105
-
with the access the eventual workload will receive without adding a separate,
106
-
incomplete permission model to OpenShell.
107
-
108
-
Image `VOLUME` declarations must not cover the workdir or one of its parents
109
-
because Docker would mount the volume before the supervisor could validate the
110
-
immutable image path.
111
-
Workdirs under the standard OCI runtime namespaces `/proc`, `/sys`, and `/dev`
112
-
are rejected, as are paths that overlap concrete OpenShell control resources.
113
-
The workspace is the child cwd and `HOME`. The supervisor starts from `/`, then
114
-
reports an invalid workdir as a readiness failure.
115
-
116
-
Docker containers join an OpenShell-managed bridge network. The driver injects
117
-
`host.openshell.internal` and `host.docker.internal` so supervisors have stable
118
-
names for reaching the gateway host. On Docker Desktop, Colima, Rancher
119
-
Desktop, OrbStack, and macOS-hosted gateways, those names use Docker's
120
-
`host-gateway` alias. The driver requests a separate IPv4 loopback callback
121
-
listener when the primary listener does not already cover it. On native Linux
122
-
Docker, the gateway also binds the bridge gateway IP so containers can call
123
-
back to the host process.
124
-
125
-
## Container Contract
126
-
127
-
The driver-controlled container settings are part of the sandbox security
128
-
contract:
129
-
130
-
| Setting | Purpose |
131
-
|---|---|
132
-
|`user = "0"`| The supervisor needs root inside the container to prepare namespaces, mounts, Landlock, and seccomp. |
133
-
|`network_mode = openshell`| Places the supervisor on the managed Docker bridge network. |
134
-
|`cap_add`| Grants supervisor-only capabilities required for namespace setup and process inspection. |
135
-
|`apparmor=unconfined`| Avoids Docker's default profile blocking required mount operations. |
136
-
|`restart_policy = no`| A canonical main-process exit remains terminal and is not silently restarted by Docker. |
137
-
|`PidsLimit`| Enforces the sandbox PID budget at the Docker cgroup layer. Set `[openshell.drivers.docker].sandbox_pids_limit = 0` to inherit the Docker/runtime default. |
138
-
| CDI GPU request | Uses opaque `driver_config.cdi_devices` values when set; otherwise selects the requested count of NVIDIA CDI GPUs in round-robin order when daemon CDI support is detected. Docker daemon `/info` can permit `nvidia.com/gpu=all` as a WSL2 all-only compatibility fallback, where it counts as one selectable device. Exact CDI device lists must not contain duplicates and must match the effective GPU count. |
139
-
|`policy-dns-transparent-tcp` capability | Declares that the combined Docker supervisor can own namespace-local DNS/TCP capture and coupled workload restart. The shared supervisor still owns DNS eligibility, mappings, authorization, pinned dialing, relaying, and OCSF decisions. The marker is stripped from the workload environment. |
140
-
141
-
The agent child process does not retain these supervisor privileges.
142
-
143
-
## Driver Config Mounts
144
-
145
-
The gateway forwards the `docker` block from `--driver-config-json` to this
146
-
driver. The driver accepts user-supplied `mounts` entries with these Docker
147
-
mount types:
148
-
149
-
-`bind`: mounts an absolute host path when `[openshell.drivers.docker]`
150
-
has `enable_bind_mounts = true`.
151
-
-`volume`: mounts an existing Docker named volume. The driver validates that
152
-
the volume exists before provisioning and never creates or removes it.
153
-
Docker local-driver volumes created with bind options are treated as host
154
-
bind mounts and require `enable_bind_mounts = true`.
155
-
-`tmpfs`: mounts an in-memory filesystem with optional `options`,
156
-
`size_bytes`, and `mode`.
157
-
158
-
Host bind mounts are disabled by default because they expose gateway host
159
-
paths to sandbox requests. Image mounts are not part of the Docker
160
-
driver-config schema. The driver still uses internal bind mounts for
161
-
OpenShell-owned supervisor, token, and TLS material.
162
-
163
-
Docker `bind` mounts accept `source`, `target`, optional `read_only`, and an
164
-
optional `selinux_label` of `shared` (applies `:z`) or `private` (applies
165
-
`:Z`) for SELinux-enforcing hosts. Docker `volume` mounts may include
166
-
`subpath`. User-supplied bind and volume mounts are read-only by default; set
167
-
`read_only: false` to make them writable. Mount `source`, `target`, and
168
-
`subpath` values must not contain surrounding whitespace. Mount targets must be
169
-
absolute container paths and must not replace or contain the resolved workspace
170
-
root. Nested workspace mounts remain valid. Mounts also must not overlap the
171
-
configured SSH socket or the reserved `/opt/openshell`, `/etc/openshell`,
172
-
`/etc/openshell-tls`, `/run/openshell`, `/run/openshell-sidecar`, and network
173
-
namespace roots.
174
-
175
-
Example named-volume usage:
44
+
The listener injects connected sockets for workload TCP and DNS operations.
45
+
DNS queries travel directly to the supervisor policy-DNS service and return
46
+
short-lived synthetic addresses. A later connection to a synthetic address is
47
+
bound to the queried hostname, calling-binary identity, allowed port, policy
48
+
generation, and pinned real addresses. The supervisor consumes these streams
49
+
without binding a container-visible proxy port or setting proxy environment
50
+
variables. Direct real-IP and non-mediated UDP traffic fail closed.
176
51
177
-
```shell
178
-
docker volume create openshell-work
52
+
For TLS termination, the backend read-only mounts the generated public CA and
53
+
combined public trust bundle. CA private key material remains in host
0 commit comments