feat(sandbox): support self-exec pattern to eliminate separate helper binary

README.md

@@ -91,17 +91,18 @@ If you are testing before the first public release, build from source:
 go build -o zero ./cmd/zero
 ```
 
-On Linux, build the sandbox helper too if you want native sandboxing:
+On Linux, native sandboxing needs Bubblewrap. The main `zero` binary re-executes
+itself as the helper when `zero-linux-sandbox` is absent. A separate helper next
+to `zero` or on `PATH` still takes precedence:
 
 ```bash
-go build -o zero-linux-sandbox ./cmd/zero-linux-sandbox
-go build -o zero-seccomp ./cmd/zero-seccomp   # optional compatibility wrapper
+go build -o zero-linux-sandbox ./cmd/zero-linux-sandbox   # optional
+go build -o zero-seccomp ./cmd/zero-seccomp               # optional compatibility wrapper
 ```
 
-Put `zero` and `zero-linux-sandbox` in the same directory on `PATH`
-(`~/.local/bin` is a good default). macOS does not need an extra helper binary.
-Windows source builds can use the main `zero.exe` as their sandbox helper; release
-archives still ship standalone Windows helper executables.
+Put `zero` on `PATH` (`~/.local/bin` is a good default). macOS does not need an
+extra helper binary. Windows source builds can use the main `zero.exe` as their
+sandbox helper; release archives still ship standalone Windows helper executables.
 
 More install details: [docs/INSTALL.md](docs/INSTALL.md).
 

README_ZH.md

@@ -71,14 +71,14 @@ go run ./cmd/zero
 go build -o zero ./cmd/zero
 ```
 
-在 Linux 上，如果你需要原生沙箱，还需要构建沙箱辅助程序：
+在 Linux 上，原生沙箱需要 Bubblewrap。主程序 `zero` 在找不到 `zero-linux-sandbox` 时会以自身作为辅助进程重新执行。同目录或 PATH 上的独立 helper 仍优先：
 
 ```bash
-go build -o zero-linux-sandbox ./cmd/zero-linux-sandbox
-go build -o zero-seccomp ./cmd/zero-seccomp   # 可选的兼容性包装器
+go build -o zero-linux-sandbox ./cmd/zero-linux-sandbox   # 可选
+go build -o zero-seccomp ./cmd/zero-seccomp               # 可选的兼容性包装器
 ```
 
-将 `zero` 和 `zero-linux-sandbox` 放在 `PATH` 上的同一目录中（`~/.local/bin` 是一个好的默认选择）。macOS 不需要额外的辅助二进制文件。Windows 源码构建可以使用主 `zero.exe` 作为沙箱辅助程序；发布包仍然附带独立的 Windows 辅助可执行文件。
+将 `zero` 放在 `PATH` 上（`~/.local/bin` 是一个好的默认选择）。macOS 不需要额外的辅助二进制文件。Windows 源码构建可以使用主 `zero.exe` 作为沙箱辅助程序；发布包仍然附带独立的 Windows 辅助可执行文件。
 
 更多安装细节：[docs/INSTALL.md](docs/INSTALL.md)。
 

cmd/zero/main.go

@@ -4,8 +4,12 @@ import (
 	"os"
 
 	"github.com/Gitlawb/zero/internal/cli"
+	"github.com/Gitlawb/zero/internal/sandbox"
 )
 
 func main() {
+	if len(os.Args) > 1 && os.Args[1] == sandbox.LinuxSandboxHelperSubcommand {
+		os.Exit(sandbox.RunLinuxSandboxHelper(os.Args[1:], os.Stderr))
+	}
 	os.Exit(cli.Run(os.Args[1:], os.Stdout, os.Stderr))
 }

docs/INSTALL.md

@@ -156,10 +156,11 @@ go install github.com/Gitlawb/zero/cmd/zero@latest
 This builds from source, so it needs Go 1.26.6+ and it does not go through the
 release archives. Two consequences worth knowing before you pick it:
 
-- On Linux you also need the sandbox helper, which is a separate binary and is
-  not installed by this command. See
+- On Linux, Bubblewrap is still required for native sandboxing. The installed
+  `zero` binary re-executes itself as the helper when no standalone
+  `zero-linux-sandbox` is available next to `zero` or on `PATH`. A colocated or
+  PATH helper remains optional and takes precedence. See
   [Sandbox Helpers For Source Builds](#sandbox-helpers-for-source-builds).
-  Without it, native sandboxing is unavailable.
 - `zero upgrade` treats the result as a standalone install and will replace the
   binary with a release build rather than rebuilding from source. If you chose
   `go install` deliberately, rerun it instead.
@@ -184,21 +185,22 @@ Source builds require Go 1.26.6+.
 
 ### Sandbox Helpers For Source Builds
 
-Release archives include the platform sandbox helpers. If you build directly
-from source, build the helpers you need:
+Release archives include the platform sandbox helpers. A source build of the
+main `zero` binary is enough for Linux native sandboxing: Zero re-executes
+itself as the helper when no standalone `zero-linux-sandbox` is available next
+to `zero` or on `PATH`. Bubblewrap must still be installed.
 
-Linux:
+A separate helper remains supported if it sits next to `zero` or on `PATH`:
 
 ```bash
 go build -o zero ./cmd/zero
-go build -o zero-linux-sandbox ./cmd/zero-linux-sandbox
-go build -o zero-seccomp ./cmd/zero-seccomp
+go build -o zero-linux-sandbox ./cmd/zero-linux-sandbox   # optional
+go build -o zero-seccomp ./cmd/zero-seccomp               # optional compatibility wrapper
 ```
 
-Put `zero` and `zero-linux-sandbox` in the same directory on `PATH`, for example
-`~/.local/bin`. `zero-seccomp` is kept as a compatibility wrapper; the sandbox
-helper applies the Unix-socket filter itself when that sandbox option is enabled.
-Linux native sandboxing also requires Bubblewrap to be installed.
+Put `zero` on `PATH`, for example `~/.local/bin`. `zero-seccomp` is kept as a
+compatibility wrapper; the sandbox helper applies the Unix-socket filter itself
+when that sandbox option is enabled.
 
 macOS uses the system sandbox and does not need an extra helper binary.
 

internal/sandbox/adapters.go

@@ -19,10 +19,10 @@ type Backend struct {
 	NativeIsolation bool        `json:"nativeIsolation"`
 	Executable      string      `json:"executable,omitempty"`
 	// ExecutableArgsPrefix is prepended to a wrapped command's args before the
-	// sandbox arguments. Non-empty only for the Windows self-dispatch helper,
-	// where Executable is the running zero binary and this carries the hidden
-	// subcommand token (e.g. "__windows-command-runner"). nil for every other
-	// backend, so their serialized form is unchanged.
+	// sandbox arguments. Non-empty for self-dispatch helpers, where Executable
+	// is the running zero binary and this carries the hidden subcommand token
+	// ("__windows-command-runner" or "__sandbox-helper"). nil for standalone
+	// helper binaries, so their serialized form is unchanged.
 	ExecutableArgsPrefix []string `json:"executableArgsPrefix,omitempty"`
 	Message              string   `json:"message,omitempty"`
 }

internal/sandbox/adapters_test.go

@@ -36,7 +36,8 @@ func TestSelectBackendChoosesPlatformAdapterWithFallback(t *testing.T) {
 		}
 	})
 
-	t.Run("linux helper missing falls back explicitly", func(t *testing.T) {
+	t.Run("linux helper missing uses self-exec when bwrap exists", func(t *testing.T) {
+		exe := fakeZeroMain(t)
 		backend := SelectBackend(BackendOptions{
 			GOOS: "linux",
 			LookupExecutable: func(name string) (string, error) {
@@ -47,11 +48,26 @@ func TestSelectBackendChoosesPlatformAdapterWithFallback(t *testing.T) {
 			},
 			DetectWSL: func() WSLInfo { return WSLInfo{} },
 		})
+		if backend.Name != BackendLinuxBwrap || !backend.Available || backend.Executable != exe {
+			t.Fatalf("linux backend = %#v, want self-exec of fake zero", backend)
+		}
+		if len(backend.ExecutableArgsPrefix) != 1 || backend.ExecutableArgsPrefix[0] != LinuxSandboxHelperSubcommand {
+			t.Fatalf("linux self-exec prefix = %#v, want [%q]", backend.ExecutableArgsPrefix, LinuxSandboxHelperSubcommand)
+		}
+	})
+
+	t.Run("linux helper and bwrap missing falls back explicitly", func(t *testing.T) {
+		backend := SelectBackend(BackendOptions{
+			GOOS: "linux",
+			LookupExecutable: func(string) (string, error) {
+				return "", errors.New("missing")
+			},
+		})
 		if backend.Name != BackendUnavailable || backend.Available {
-			t.Fatalf("linux backend = %#v, want native sandbox unavailable without Linux helper", backend)
+			t.Fatalf("linux backend = %#v, want native sandbox unavailable without bwrap", backend)
 		}
-		if !strings.Contains(backend.Message, "Linux sandbox helper is not available") {
-			t.Fatalf("linux fallback message = %q, want missing helper", backend.Message)
+		if !strings.Contains(backend.Message, "bubblewrap is not installed") && !strings.Contains(backend.Message, "Linux sandbox helper is not available") {
+			t.Fatalf("linux fallback message = %q, want missing bwrap or helper", backend.Message)
 		}
 	})
 

internal/sandbox/linux_helper.go

@@ -16,6 +16,8 @@ import (
 
 const LinuxSandboxHelperName = "zero-linux-sandbox"
 
+const LinuxSandboxHelperSubcommand = "__sandbox-helper"
+
 const linuxSandboxBackendEnv = BackendLinuxBwrap
 
 type LinuxSandboxCommandArgsOptions struct {
@@ -51,6 +53,7 @@ type LinuxSandboxHelperCommand struct {
 type LinuxSandboxBwrapOptions struct {
 	Config     LinuxSandboxHelperConfig
 	HelperPath string
+	SelfExec   bool
 }
 
 type linuxSandboxBwrapPlan struct {
@@ -213,6 +216,9 @@ func buildLinuxSandboxBwrapPlan(options LinuxSandboxBwrapOptions) (linuxSandboxB
 		}
 	}
 	args = append(args, "--", helperPath)
+	if options.SelfExec {
+		args = append(args, LinuxSandboxHelperSubcommand)
+	}
 	args = append(args, innerArgs...)
 	return linuxSandboxBwrapPlan{
 		Args:                   args,
@@ -472,14 +478,8 @@ func pathExists(path string) bool {
 }
 
 func findLinuxSandboxHelperCommand() (LinuxSandboxHelperCommand, error) {
-	if exe, err := os.Executable(); err == nil {
-		candidate := filepath.Join(filepath.Dir(exe), LinuxSandboxHelperName)
-		if executableRegularFile(candidate) {
-			return LinuxSandboxHelperCommand{Name: candidate}, nil
-		}
-	}
-	if path, err := exec.LookPath(LinuxSandboxHelperName); err == nil && path != "" {
-		return LinuxSandboxHelperCommand{Name: path}, nil
+	if cmd := resolveLinuxSandboxHelper(lookupExecutable); cmd.Name != "" {
+		return cmd, nil
 	}
 	if root := linuxSandboxRepoRoot(); root != "" {
 		mainPath := filepath.Join(root, "cmd", LinuxSandboxHelperName, "main.go")
@@ -496,6 +496,41 @@ func findLinuxSandboxHelperCommand() (LinuxSandboxHelperCommand, error) {
 	return LinuxSandboxHelperCommand{}, errors.New("zero-linux-sandbox helper is not available")
 }
 
+var linuxSandboxExecutable = os.Executable
+
+func resolveLinuxSandboxHelper(lookup func(string) (string, error)) LinuxSandboxHelperCommand {
+	if lookup == nil {
+		lookup = lookupExecutable
+	}
+	if exe, err := linuxSandboxExecutable(); err == nil {
+		candidate := filepath.Join(filepath.Dir(exe), LinuxSandboxHelperName)
+		if linuxFileIsExecutable(candidate) {
+			return LinuxSandboxHelperCommand{Name: candidate}
+		}
+	}
+	if path, err := lookup(LinuxSandboxHelperName); err == nil && strings.TrimSpace(path) != "" {
+		return LinuxSandboxHelperCommand{Name: path}
+	}
+	if exe, err := linuxSandboxExecutable(); err == nil && linuxFileIsExecutable(exe) && linuxMainBinaryName(exe) {
+		return LinuxSandboxHelperCommand{
+			Name:       exe,
+			ArgsPrefix: []string{LinuxSandboxHelperSubcommand},
+		}
+	}
+	return LinuxSandboxHelperCommand{}
+}
+
+func linuxMainBinaryName(path string) bool {
+	switch filepath.Base(path) {
+	case "zero", "zero.exe":
+		return true
+	default:
+		return false
+	}
+}
+
+var linuxFileIsExecutable = executableRegularFile
+
 func executableRegularFile(path string) bool {
 	info, err := os.Stat(path)
 	return err == nil && info.Mode().IsRegular() && info.Mode().Perm()&0o111 != 0

internal/sandbox/linux_helper_linux.go

@@ -16,6 +16,11 @@ var (
 )
 
 func RunLinuxSandboxHelper(args []string, stderr io.Writer) int {
+	selfExec := false
+	if len(args) > 0 && args[0] == LinuxSandboxHelperSubcommand {
+		selfExec = true
+		args = args[1:]
+	}
 	config, err := ParseLinuxSandboxHelperArgs(args)
 	if err != nil {
 		fmt.Fprintln(stderr, LinuxSandboxHelperName+": "+err.Error())
@@ -35,6 +40,7 @@ func RunLinuxSandboxHelper(args []string, stderr io.Writer) int {
 	bwrapPlan, err := buildLinuxSandboxBwrapPlan(LinuxSandboxBwrapOptions{
 		Config:     config,
 		HelperPath: helperPath,
+		SelfExec:   selfExec,
 	})
 	if err != nil {
 		fmt.Fprintln(stderr, LinuxSandboxHelperName+": "+err.Error())

internal/sandbox/linux_helper_other.go

@@ -8,6 +8,9 @@ import (
 )
 
 func RunLinuxSandboxHelper(args []string, stderr io.Writer) int {
+	if len(args) > 0 && args[0] == LinuxSandboxHelperSubcommand {
+		args = args[1:]
+	}
 	if _, err := ParseLinuxSandboxHelperArgs(args); err != nil {
 		fmt.Fprintln(stderr, LinuxSandboxHelperName+": "+err.Error())
 		return 2

internal/sandbox/linux_helper_test.go

@@ -10,6 +10,27 @@ import (
 	"testing"
 )
 
+func fakeZeroMain(t *testing.T) string {
+	t.Helper()
+	name := "zero"
+	if runtime.GOOS == "windows" {
+		name = "zero.exe"
+	}
+	path := filepath.Join(t.TempDir(), name)
+	if err := os.WriteFile(path, []byte("x"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	restoreExec := linuxSandboxExecutable
+	restoreFile := linuxFileIsExecutable
+	t.Cleanup(func() {
+		linuxSandboxExecutable = restoreExec
+		linuxFileIsExecutable = restoreFile
+	})
+	linuxSandboxExecutable = func() (string, error) { return path, nil }
+	linuxFileIsExecutable = func(p string) bool { return p == path }
+	return path
+}
+
 func TestBuildLinuxSandboxCommandArgsSerializesPermissionProfile(t *testing.T) {
 	profile := PermissionProfile{
 		FileSystem: FileSystemPolicy{
@@ -463,6 +484,64 @@ func indexString(values []string, want string) int {
 	return -1
 }
 
+func TestFindLinuxSandboxHelperCommandSelfExec(t *testing.T) {
+	cmd, err := findLinuxSandboxHelperCommand()
+	if err != nil {
+		t.Fatalf("findLinuxSandboxHelperCommand failed: %v", err)
+	}
+	if cmd.Name == "" {
+		t.Fatal("expected non-empty command name")
+	}
+	// When self-exec is selected, ArgsPrefix must contain __sandbox-helper
+	if len(cmd.ArgsPrefix) > 0 && cmd.ArgsPrefix[0] == "__sandbox-helper" {
+		exe, err := os.Executable()
+		if err != nil {
+			t.Fatalf("os.Executable: %v", err)
+		}
+		if cmd.Name != exe {
+			t.Fatalf("cmd.Name = %q, want os.Executable %q", cmd.Name, exe)
+		}
+	}
+}
+
+func TestBuildLinuxSandboxBwrapPlanVersionedStandaloneOmitsVerb(t *testing.T) {
+	plan, err := buildLinuxSandboxBwrapPlan(LinuxSandboxBwrapOptions{
+		Config: LinuxSandboxHelperConfig{
+			SandboxPolicyCWD: t.TempDir(),
+			CommandCWD:       t.TempDir(),
+			Command:          []string{"echo", "hello"},
+		},
+		HelperPath: "/usr/local/bin/zero-linux-sandbox-v1",
+	})
+	if err != nil {
+		t.Fatalf("buildLinuxSandboxBwrapPlan failed: %v", err)
+	}
+	if argsContainSequence(plan.Args, "__sandbox-helper") {
+		t.Fatalf("versioned standalone helper must not get __sandbox-helper: %v", plan.Args)
+	}
+	if !argsContainSequence(plan.Args, "--", "/usr/local/bin/zero-linux-sandbox-v1", "--sandbox-policy-cwd") {
+		t.Fatalf("expected flags directly after versioned helper path: %v", plan.Args)
+	}
+}
+
+func TestBuildLinuxSandboxBwrapPlanSelfExecInsertsHelperVerb(t *testing.T) {
+	plan, err := buildLinuxSandboxBwrapPlan(LinuxSandboxBwrapOptions{
+		Config: LinuxSandboxHelperConfig{
+			SandboxPolicyCWD: t.TempDir(),
+			CommandCWD:       t.TempDir(),
+			Command:          []string{"echo", "hello"},
+		},
+		HelperPath: "/usr/local/bin/zero",
+		SelfExec:   true,
+	})
+	if err != nil {
+		t.Fatalf("buildLinuxSandboxBwrapPlan failed: %v", err)
+	}
+	if !argsContainSequence(plan.Args, "--", "/usr/local/bin/zero", "__sandbox-helper", "--sandbox-policy-cwd") {
+		t.Fatalf("bwrap plan args missing __sandbox-helper after self-exec helperPath: %v", plan.Args)
+	}
+}
+
 func argsContainSequence(args []string, sequence ...string) bool {
 	return argsSequenceIndex(args, sequence...) >= 0
 }

internal/sandbox/manager.go

@@ -178,11 +178,13 @@ func selectPlatformBackend(goos string, lookup func(string) (string, error), det
 	}
 	switch goos {
 	case "linux":
-		if helper, err := lookup(LinuxSandboxHelperName); err == nil && helper != "" {
+		if helper := resolveLinuxSandboxHelper(lookup); helper.Name != "" {
 			if _, bwrapErr := lookup("bwrap"); bwrapErr != nil {
 				return unavailableBackend(goos, "bubblewrap is not installed")
 			}
-			return nativeBackend(goos, BackendLinuxBwrap, helper, "Linux sandbox helper available")
+			backend := nativeBackend(goos, BackendLinuxBwrap, helper.Name, "Linux sandbox helper available")
+			backend.ExecutableArgsPrefix = helper.ArgsPrefix
+			return backend
 		}
 		if info := detect(); info.IsWSL {
 			return wslBackend(goos, info)