Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

feat(templates): bake EXECD_INIT into fsb golden images when runtime.execd_run_as_init is set

高然df5c120cf210
diff --git a/docs/architecture/fast-sandbox/templates.md b/docs/architecture/fast-sandbox/templates.md
index 6a57b7f4d..c6f73af60 100644
--- a/docs/architecture/fast-sandbox/templates.md
+++ b/docs/architecture/fast-sandbox/templates.md
@@ -20,7 +20,7 @@ Builds are asynchronous by design: the API returns an accepted state immediately
A `SandboxTemplate` describes a conversion, not just a copy: an ordinary OCI image plus the OpenSandbox guest wiring, compiled into an immutable golden image.
-- **Guest wiring is injected**: an init path (PID 1, carrying the readiness marker and heartbeat) and the execd runtime files always come from the template — every sandbox built from it is execd-ready by construction.
+- **Guest wiring is injected**: an init path (PID 1, carrying the readiness marker and heartbeat) and the execd runtime files always come from the template — every sandbox built from it is execd-ready by construction. With the server's `runtime.execd_run_as_init` enabled, the server bakes `EXECD_INIT=1` into the template envs, so the baked `bootstrap.sh` execs into `execd --init` and execd becomes the root of the workload tree as a subreaper under the guest init (child reaping, signal forwarding, and the optional hardening floor; the PID 1 signal shield stays with the guest init).
- **Business entrypoint and envs** are baked in: an empty entrypoint defaults to a keep-alive; envs are injected literally into the guest (no runtime indirection).
- **Runtime shape is declared**: the template names the Firecracker guest kernel and reference machine; readiness defines when the guest counts as up.
- **Output is content-addressed**: the build publishes artifacts to the store and records a manifest reference plus artifact digest in the CR status — builds are immutable and verifiable, never mutated in place.
diff --git a/server/configuration.md b/server/configuration.md
index b5540dcb9..fb90185e8 100644
--- a/server/configuration.md
+++ b/server/configuration.md
@@ -99,7 +99,7 @@ Example files: [`example.config.toml`](opensandbox_server/examples/example.confi
|-----|------|---------|-------------|
| `type` | string | — | **`docker`** or **`kubernetes`**. |
| `execd_image` | string | — | OCI image containing the **execd** binary (in-sandbox bootstrap). |
-| `execd_run_as_init` | boolean | `false` | Run execd as sandbox init (OSEP-0018): execd becomes PID 1 (child reaping, container lifecycle, hardening floor). |
+| `execd_run_as_init` | boolean | `false` | Run execd as sandbox init (OSEP-0018): execd becomes PID 1 (child reaping, container lifecycle, hardening floor). fsb template builds bake `EXECD_INIT=1` into the golden image instead: execd runs as a subreaper under the fsb guest init, so reaping, signal forwarding, and the hardening floor still apply but the PID 1 signal shield does not. |
---
diff --git a/server/opensandbox_server/services/templates/template_service.py b/server/opensandbox_server/services/templates/template_service.py
index 77d64d7aa..058d3c22a 100644
--- a/server/opensandbox_server/services/templates/template_service.py
+++ b/server/opensandbox_server/services/templates/template_service.py
@@ -61,6 +61,14 @@ PLURAL = "sandboxtemplates"
# exist in the sandboxtemplate-builder image under this name (builder
# default); execd comes from runtime.execd_image.
TEMPLATE_KERNEL = "vmlinux.bin"
+# OSEP-0018 on fsb: the golden image's guest init sources the baked envs and
+# launches /opt/opensandbox/bootstrap.sh, so a baked EXECD_INIT=1 makes
+# bootstrap.sh exec into `execd --init` and execd becomes the root of the
+# workload tree — a subreaper, since the fsb guest init stays PID 1 (no
+# PID 1 signal shield, same tier as the Kubernetes Pool path). Injected at
+# CRD projection from runtime.execd_run_as_init; the server value wins over
+# a client-provided env of the same name.
+EXECD_INIT_ENV = "EXECD_INIT"
DEFAULT_VCPU = "1"
DEFAULT_MEMORY = "512Mi"
# Guest rootfs logical size when the client omits resourceLimits.disk. The
@@ -163,6 +171,7 @@ class FastSandboxTemplateService:
):
self._config = config
self._execd_image = config.runtime.execd_image
+ self._execd_run_as_init = bool(config.runtime.execd_run_as_init)
self._repository = repository
self._k8s_client = k8s_client
self._k8s_config = config.kubernetes or KubernetesRuntimeConfig()
@@ -517,6 +526,10 @@ class FastSandboxTemplateService:
},
}
env = record.spec.get("env") or {}
+ if self._execd_run_as_init:
+ # Copy first: the stored row keeps the client env untouched, and
+ # the server value wins over a client-provided EXECD_INIT.
+ env = {**env, EXECD_INIT_ENV: "1"}
if env:
spec["envs"] = [{"name": name, "value": value} for name, value in env.items()]
# OSEP-0022 CA wiring: bake the pinned MITM CA Secret's certificate
diff --git a/server/tests/test_templates.py b/server/tests/test_templates.py
index 33ef6a237..80eb5b953 100644
--- a/server/tests/test_templates.py
+++ b/server/tests/test_templates.py
@@ -399,6 +399,42 @@ def test_create_projects_env_to_crd(service, crs):
assert "envs" not in crs.created[-1]["spec"]
+def execd_init_service(repo, crs, monkeypatch):
+ monkeypatch.setattr(WorkloadInformer, "start", lambda self: None)
+ with patch.object(K8sClient, "_load_config"):
+ k8s = K8sClient(KubernetesRuntimeConfig())
+ crs.install(k8s)
+ config = _config()
+ config.runtime.execd_run_as_init = True
+ svc = FastSandboxTemplateService(config, repository=repo, k8s_client=k8s)
+ yield svc
+ svc.close()
+
+
+def test_create_injects_execd_init_env_when_enabled(execd_init_service, crs):
+ # A client-provided EXECD_INIT must not win over the server switch.
+ record = execd_init_service.create_template(
+ _create_request(env={"EXECD_INIT": "0", "LOG_LEVEL": "info"})
+ )
+ envs = {e["name"]: e["value"] for e in crs.created[-1]["spec"]["envs"]}
+ assert envs == {"EXECD_INIT": "1", "LOG_LEVEL": "info"}
+ # The stored row keeps the client env; injection is projection-only.
+ assert record.spec["env"] == {"EXECD_INIT": "0", "LOG_LEVEL": "info"}
+
+ execd_init_service.create_template(_create_request())
+ assert crs.created[-1]["spec"]["envs"] == [{"name": "EXECD_INIT", "value": "1"}]
+
+
+def test_create_does_not_inject_execd_init_by_default(service, crs):
+ service.create_template(_create_request(env={"LOG_LEVEL": "info"}))
+ envs = {e["name"]: e["value"] for e in crs.created[-1]["spec"]["envs"]}
+ assert envs == {"LOG_LEVEL": "info"}
+
+ service.create_template(_create_request())
+ assert "envs" not in crs.created[-1]["spec"]
+
+
def test_create_rejects_invalid_env_names(service):
from fastapi import HTTPException