SaladDay · Oct 28, 2026 · Oct 28, 2026 · Oct 28, 2026
diff --git a/docs/maintainers.md b/docs/maintainers.md
@@ -33,7 +33,7 @@ make build-core-distribution
 | `OAC_NATIVE_INSTALLER_BUILD_DIR` | Native installer catalog directory; see [Native installers](#native-installers) |
 | `CORE_DISTRIBUTION_BUILD_DIR` | Output directory under `~/.oac`. Default: `~/.oac/build/core-distribution` |
 | `CORE_DISTRIBUTION_BUILD_NETWORK` | Docker build network: `default`, `host` or `none` |
-| `CORE_DISTRIBUTION_MICROSANDBOX_ARCHIVE` | Cached microsandbox release archive. Default: `~/.oac/cache/microsandbox-v0.7.8-linux-x86_64.tar.gz`, downloaded when missing |
+| `CORE_DISTRIBUTION_MICROSANDBOX_ARCHIVE` | Cached microsandbox release archive. Default: `~/.oac/cache/microsandbox-v0.7.11-linux-x86_64.tar.gz`, downloaded when missing |
 | `CORE_DISTRIBUTION_DATABASE_IMAGE` | PostgreSQL 16 image; the default is the linux/amd64 manifest of the index in `deploy/compose/database-image.txt` |
 
 The build reuses the Core, Web, Runtime, SDK and helper builders. The manifest records the commit and its source tree, image config and OCI manifest digests, the Runtime OCI manifest digest, the microsandbox runtime and firmware hashes, and the size and SHA-256 of every Runtime and node artifact; native installers carry only their SHA-256 in the [catalog](#native-installers). Output is the control archive and its `.sha256`, the optional offline archive, and the versioned Runtime, node and native installer assets. Nothing is published. Rebuilding into a directory that already holds this commit's distribution is refused.
@@ -112,9 +112,11 @@ make build-microsandbox-provider
 make check-microsandbox-provider
 ```
 
-The helper is written to `~/.oac/build/microsandbox-provider/oac-microsandbox-provider`. Its separate Go module pins the official microsandbox SDK source commit. Both commands and the distribution build use `scripts/build-microsandbox-provider.py`: it stages the module dependencies, verifies the matching official FFI release checksum, fills the SDK's empty release bundle and builds with that FFI embedded. The SDK source is unchanged and no vendored binary is committed. Use this entry point rather than invoking `go build` directly; never build production with the SDK's `microsandbox_ffi_path` tag. Core itself stays a CGO-disabled build. The helper needs glibc and runs only on nodes.
+The helper is written to `~/.oac/build/microsandbox-provider/oac-microsandbox-provider`. Its separate Go module pins the microsandbox SDK from the fork described below. Both commands and the distribution build use `scripts/build-microsandbox-provider.py`: it stages the module dependencies, verifies the checksum of the fork's FFI release, fills the SDK's empty release bundle and builds with that FFI embedded. No vendored binary is committed. Use this entry point rather than invoking `go build` directly; never build production with the SDK's `microsandbox_ffi_path` tag. Core itself stays a CGO-disabled build. The helper needs glibc and runs only on nodes.
 
-**microsandbox runtime.** The distribution uses the official [v0.7.8 release](https://github.com/superradcompany/microsandbox/releases/tag/v0.7.8) archive `microsandbox-linux-x86_64.tar.gz`, SHA256 `86f9f72dc3e639c7175bc07909b4b63ce412517c1ef8a2e1921171af5682fded` (`RUNTIME_ARCHIVE_SHA256` in `scripts/core-distribution-manifest.py`). The build verifies the checksum before extracting `msb` and `libkrunfw.so.5.6.1` and records both files' hashes. The helper checks those hashes on every call and never installs or upgrades them.
+**microsandbox runtime.** The distribution uses the official [v0.7.11 release](https://github.com/superradcompany/microsandbox/releases/tag/v0.7.11) archive `microsandbox-linux-x86_64.tar.gz`, SHA256 `5fc2206fbe35b471743bd5af15e3931cd2439a0c8b8e6ef08a493ddabcdc1b4c` (`RUNTIME_ARCHIVE_SHA256` in `scripts/core-distribution-manifest.py`). The build verifies the checksum before extracting `msb` and `libkrunfw.so.5.6.1` and records both files' hashes. The helper checks those hashes on every call and never installs or upgrades them.
+
+**microsandbox fork.** The SDK and its FFI come from the `oac` branch of [SaladDay/microsandbox](https://github.com/SaladDay/microsandbox/tree/oac): an upstream release tag plus a short queue of patches, listed by `git log v0.7.11..oac`. Each patch is also proposed upstream and dropped once an upstream release carries it. Pushing a tag `oac-v<upstream version>-<n>` builds the Linux amd64 FFI in the same manylinux 2.28 container as upstream releases and attaches it, with its SHA256, to a release of that tag. To move to a new tag, point the SDK `replace` in `services/core/tools/microsandbox-provider/go.mod` at the tagged commit and update `FFI_URL` and `FFI_SHA256` in `scripts/build-microsandbox-provider.py`. The runtime stays the official release of the same upstream version.
 
 ### Standalone Core builds
 

diff --git a/docs/zh/maintainers.md b/docs/zh/maintainers.md
@@ -1,7 +1,7 @@
 ---
 title: "构建并发布 OpenAgentCore"
 source: docs/maintainers.md
-source_hash: d222cc5fe4c258dcc4e8956c08757276dc6340511c5eaf2e0fba2698e6718761
+source_hash: 7a78188dee1e8010194c3aef618b33027f1fb1fd2401b4d80c9b21beea85d34b
 ---
 
 本指南面向负责构建和发布 OpenAgentCore 的维护者。要安装 Core 和 Web，请按 [安装 Core 和 Web](getting-started/install.md) 操作。安装程序代码遵循的规则见 [部署](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/deploy/README.md) 和 [节点安装程序](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/deploy/node/README.md)；必需检查见 [CONTRIBUTING](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/CONTRIBUTING.md#required-checks)。
@@ -35,7 +35,7 @@ make build-core-distribution
 | `OAC_NATIVE_INSTALLER_BUILD_DIR` | 原生安装程序目录；请参阅[原生安装程序](#native-installers) |
 | `CORE_DISTRIBUTION_BUILD_DIR` | `~/.oac` 下的输出目录。默认值：`~/.oac/build/core-distribution` |
 | `CORE_DISTRIBUTION_BUILD_NETWORK` | Docker 构建网络：`default`、`host` 或 `none` |
-| `CORE_DISTRIBUTION_MICROSANDBOX_ARCHIVE` | 已缓存的 microsandbox 发布归档。默认值：`~/.oac/cache/microsandbox-v0.7.8-linux-x86_64.tar.gz`，缺失时下载 |
+| `CORE_DISTRIBUTION_MICROSANDBOX_ARCHIVE` | 已缓存的 microsandbox 发布归档。默认值：`~/.oac/cache/microsandbox-v0.7.11-linux-x86_64.tar.gz`，缺失时下载 |
 | `CORE_DISTRIBUTION_DATABASE_IMAGE` | PostgreSQL 16 镜像；默认值为 `deploy/compose/database-image.txt` 中索引的 linux/amd64 清单 |
 
 构建过程会复用 Core、Web、Runtime、SDK 和辅助程序构建器。清单会记录提交及其源代码树、镜像配置及 OCI 清单摘要、Runtime OCI 清单摘要、microsandbox 运行时和固件哈希，以及每个 Runtime 和节点构件的大小与 SHA-256；原生安装程序在[目录](#native-installers)中仅记录其 SHA-256。输出包括控制归档及其 `.sha256`、可选的离线归档，以及带版本号的 Runtime、节点和原生安装程序资源。此过程不会发布任何内容。如果目标目录中已包含此提交的分发包，重建会拒绝执行。
@@ -114,9 +114,11 @@ make build-microsandbox-provider
 make check-microsandbox-provider
 ```
 
-该辅助程序会写入 `~/.oac/build/microsandbox-provider/oac-microsandbox-provider`。其独立的 Go 模块固定官方 microsandbox SDK 源码提交。上述两个命令与分发构建均使用 `scripts/build-microsandbox-provider.py`：它暂存模块依赖，验证匹配的官方 FFI 发行文件校验和，填充 SDK 的空发行包，并构建嵌入该 FFI 的程序。SDK 源码保持不变，仓库不提交 vendored 二进制文件。请使用此入口，而非直接调用 `go build`；构建生产版本时，绝不能使用该 SDK 的 `microsandbox_ffi_path` 标签。Core 本身仍采用禁用 CGO 的构建。该辅助程序需要 glibc，并且只能在节点上运行。
+该辅助程序会写入 `~/.oac/build/microsandbox-provider/oac-microsandbox-provider`。其独立的 Go 模块固定来自下文所述 fork 的 microsandbox SDK。上述两个命令与分发构建均使用 `scripts/build-microsandbox-provider.py`：它暂存模块依赖，验证 fork 的 FFI 发行文件校验和，填充 SDK 的空发行包，并构建嵌入该 FFI 的程序。仓库不提交 vendored 二进制文件。请使用此入口，而非直接调用 `go build`；构建生产版本时，绝不能使用该 SDK 的 `microsandbox_ffi_path` 标签。Core 本身仍采用禁用 CGO 的构建。该辅助程序需要 glibc，并且只能在节点上运行。
 
-**microsandbox 运行时。** 分发包使用官方的 [v0.7.8 release](https://github.com/superradcompany/microsandbox/releases/tag/v0.7.8) 归档 `microsandbox-linux-x86_64.tar.gz`，SHA256 为 `86f9f72dc3e639c7175bc07909b4b63ce412517c1ef8a2e1921171af5682fded`（即 `scripts/core-distribution-manifest.py` 中的 `RUNTIME_ARCHIVE_SHA256`）。构建过程会先验证校验和，再解压 `msb` 和 `libkrunfw.so.5.6.1`，并记录这两个文件的哈希。辅助程序会在每次调用时检查这些哈希，并且绝不安装或升级它们。
+**microsandbox 运行时。** 分发包使用官方的 [v0.7.11 release](https://github.com/superradcompany/microsandbox/releases/tag/v0.7.11) 归档 `microsandbox-linux-x86_64.tar.gz`，SHA256 为 `5fc2206fbe35b471743bd5af15e3931cd2439a0c8b8e6ef08a493ddabcdc1b4c`（即 `scripts/core-distribution-manifest.py` 中的 `RUNTIME_ARCHIVE_SHA256`）。构建过程会先验证校验和，再解压 `msb` 和 `libkrunfw.so.5.6.1`，并记录这两个文件的哈希。辅助程序会在每次调用时检查这些哈希，并且绝不安装或升级它们。
+
+**microsandbox fork。** SDK 及其 FFI 来自 [SaladDay/microsandbox](https://github.com/SaladDay/microsandbox/tree/oac) 的 `oac` 分支：一个上游发布标签加上一小队补丁，补丁列表见 `git log v0.7.11..oac`。每个补丁同时向上游提交，上游发布包含它之后就从队列中删除。推送 `oac-v<upstream version>-<n>` 标签会在与上游发布相同的 manylinux 2.28 容器中构建 Linux amd64 FFI，并连同其 SHA256 附加到该标签的 release。要换到新标签，把 `services/core/tools/microsandbox-provider/go.mod` 中 SDK 的 `replace` 指向该标签的提交，并更新 `scripts/build-microsandbox-provider.py` 中的 `FFI_URL` 和 `FFI_SHA256`。运行时仍使用同一上游版本的官方发布。
 
 ### 独立 Core 构建 {#standalone-core-builds}
 

diff --git a/scripts/build-core-distribution.sh b/scripts/build-core-distribution.sh
@@ -119,11 +119,11 @@ cp deploy/compose/compose.yaml "$bundle/compose.yaml.template"
 OAC_DEV_BUILD_REVISION="$revision" scripts/build-core-image-context.sh "$stage/core"
 cp "$stage/core/bin/oac" "$bundle/oac"
 python3 scripts/build-microsandbox-provider.py build "$stage/core/bin/oac-microsandbox-provider"
-msb_archive="${CORE_DISTRIBUTION_MICROSANDBOX_ARCHIVE:-$runtime_root/cache/microsandbox-v0.7.8-linux-x86_64.tar.gz}"
+msb_archive="${CORE_DISTRIBUTION_MICROSANDBOX_ARCHIVE:-$runtime_root/cache/microsandbox-v0.7.11-linux-x86_64.tar.gz}"
 if [[ ! -f "$msb_archive" ]]; then
   mkdir -p "$(dirname "$msb_archive")"
   curl --fail --location --proto '=https' --tlsv1.2 \
-    https://github.com/superradcompany/microsandbox/releases/download/v0.7.8/microsandbox-linux-x86_64.tar.gz \
+    https://github.com/superradcompany/microsandbox/releases/download/v0.7.11/microsandbox-linux-x86_64.tar.gz \
     --output "$stage/microsandbox.download"
   python3 scripts/core-distribution-manifest.py extract-runtime "$stage/microsandbox.download" "$stage/core/microsandbox"
   mv "$stage/microsandbox.download" "$msb_archive"

diff --git a/scripts/build-microsandbox-provider.py b/scripts/build-microsandbox-provider.py
@@ -1,19 +1,21 @@
 #!/usr/bin/env python3
-"""Build the provider with the official SDK source and matching embedded FFI."""
+"""Build the provider with the pinned SDK fork and its matching embedded FFI."""
 
 import argparse
 import hashlib
 import json
 import os
 from pathlib import Path
-import re
 import shutil
 import subprocess
 import tempfile
 
 SDK_MODULE = "github.com/superradcompany/microsandbox/sdk/go"
-FFI_SHA256 = "bc079888050a92d3652191ae8e18fba96e1ac66dc78bce4e5aaeb7eca9b04e25"
+# The SDK source (go.mod replace) and this FFI come from the same tag of the fork; see docs/maintainers.md.
+SDK_FORK = "github.com/SaladDay/microsandbox/sdk/go"
 FFI_FILE = "libmicrosandbox_go_ffi-linux-amd64.so"
+FFI_URL = "https://github.com/SaladDay/microsandbox/releases/download/oac-v0.7.11-1/" + FFI_FILE
+FFI_SHA256 = "e489ea93cab3b9c8ea9e8b53a5c0b4fe0e54a66be34b7b2638fb360b1d574642"
 
 
 def verify_ffi(path):
@@ -22,13 +24,13 @@ def verify_ffi(path):
         for block in iter(lambda: stream.read(1024 * 1024), b""):
             digest.update(block)
     if digest.hexdigest() != FFI_SHA256:
-        raise ValueError("Official microsandbox FFI checksum mismatch")
+        raise ValueError("microsandbox FFI checksum mismatch")
 
 
 def install_ffi(source, destination):
     verify_ffi(source)
     if destination.is_symlink() or not destination.is_file() or destination.stat().st_size != 0:
-        raise ValueError("Official SDK must contain an empty FFI release sentinel")
+        raise ValueError("The SDK must contain an empty FFI release sentinel")
     shutil.copyfile(source, destination)
 
 
@@ -54,12 +56,8 @@ def run(*command, cwd=module):
         parser.error("the provider distribution requires Linux amd64")
     run("go", "mod", "download", SDK_MODULE)
     sdk = json.loads(run("go", "list", "-mod=readonly", "-m", "-json", SDK_MODULE))
-    if "Replace" in sdk:
-        raise ValueError("The SDK must be the pinned official module")
-    versions = re.findall(r'^const sdkVersion = "([0-9.]+)"$', (Path(sdk["Dir"]) / "setup.go").read_text(), re.M)
-    if len(versions) != 1:
-        raise ValueError("Official SDK release declaration changed")
-    version = versions[0]
+    if sdk.get("Replace", {}).get("Path") != SDK_FORK:
+        raise ValueError("The SDK must be the pinned fork module")
     cache = Path(os.environ.get("OAC_DEV_HOME", str(Path.home() / ".oac"))) / "cache"
     if not cache.is_absolute():
         raise ValueError("OAC_DEV_HOME must be absolute")
@@ -69,8 +67,7 @@ def run(*command, cwd=module):
         stage = Path(temporary)
         if not ffi.exists():
             download = stage / FFI_FILE
-            run("curl", "--fail", "--location", "--silent", "--show-error", "--retry", "3", "--output", str(download),
-                f"https://github.com/superradcompany/microsandbox/releases/download/v{version}/{FFI_FILE}")
+            run("curl", "--fail", "--location", "--silent", "--show-error", "--retry", "3", "--output", str(download), FFI_URL)
             verify_ffi(download)
             os.replace(download, ffi)
         verify_ffi(ffi)

diff --git a/scripts/core-distribution-manifest.py b/scripts/core-distribution-manifest.py
@@ -17,7 +17,7 @@
 import zipapp
 
 
-RUNTIME_ARCHIVE_SHA256 = "86f9f72dc3e639c7175bc07909b4b63ce412517c1ef8a2e1921171af5682fded"
+RUNTIME_ARCHIVE_SHA256 = "5fc2206fbe35b471743bd5af15e3931cd2439a0c8b8e6ef08a493ddabcdc1b4c"
 DIGEST = re.compile(r"sha256:[0-9a-f]{64}\Z")
 sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1] / "deploy/node"))
 import provider_assets
@@ -210,7 +210,7 @@ def verify_runtime(image, daemon, source):
 
 def extract_runtime(archive, destination):
     if sha256(archive) != RUNTIME_ARCHIVE_SHA256:
-        raise ValueError("microsandbox v0.7.8 release checksum mismatch")
+        raise ValueError("microsandbox v0.7.11 release checksum mismatch")
     destination = pathlib.Path(destination)
     destination.mkdir(parents=True, exist_ok=True)
     with tarfile.open(archive, "r:gz") as bundle:
@@ -355,7 +355,7 @@ def node_payload(bundle, stage, revision, source_tree, artifact_base_url="", off
         "image_manifest_digests": {name: identity[1] for name, identity in identities.items()},
         "runtime_ref": "oac-runtime@" + digest,
         "microsandbox": {
-            "version": "0.7.8",
+            "version": "0.7.11",
             "runtime_sha256": sha256(stage / "core/microsandbox/msb"),
             "firmware_sha256": sha256(stage / "core/microsandbox/libkrunfw.so.5.6.1"),
         },

diff --git a/services/core/internal/sandbox/microsandbox/types.go b/services/core/internal/sandbox/microsandbox/types.go
@@ -10,7 +10,7 @@ import (
 )
 
 const ProtocolVersion = 9
-const SDKVersion = "v0.7.8"
+const SDKVersion = "v0.7.11"
 const MaxOutputBytes = 1024 * 1024
 const MaxRequestBytes = 72 * 1024 * 1024
 const MaxResponseBytes = 16 * 1024 * 1024