Self-hosted workflows for coding-agent delivery. Orchestrate CodeBuddy, Codex and Claude Code with scripts and human approval gates. Includes Local workflows for coding assistants.
JavaScript agent-orchestrationagentic-workflowai-agentsai-codingclaude-codecode-reviewcodebuddycodexcoding-agentscursordeveloper-toolshuman-on-the-loopllmmcpmulti-agentsdlcself-hostedsopworkflow-automationworkflow-engine
package runtime
import (
"agentflow/internal/domain"
"agentflow/internal/procwatch"
"context"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"log"
"os"
"os/exec"
"path/filepath"
"sort"
"strings"
"sync"
"time"
)
type dockerSandbox struct {
id, name, workspace string
profile domain.SandboxProfile
requirements SandboxRequirements
dockerfile domain.DockerfileDefinition
builtImage string
mu sync.Mutex
browserMu sync.Mutex
started bool
cliSetupOnce sync.Once
cliSetupGate chan struct{}
// execGate lets parallel branches exec concurrently (read side) while a
// cwd-recovery Recreate (write side) waits for them instead of docker
// rm-ing the container under a sibling's running command.
execGate sync.RWMutex
}
func (s *dockerSandbox) ID() string { return s.id }
func (s *dockerSandbox) Workspace() string { return s.workspace }
func (s *dockerSandbox) Driver() string { return "docker" }
// Close tears the sandbox down by name rather than by the in-memory started
// flag. A worker that restarted inherits a live container but a fresh struct
// with started=false and no builtImage, so trusting those fields leaks the
// container and its image for good: nothing else ever removes them, and Docker
// cannot prune a container that is still "running".
func (s *dockerSandbox) Close(ctx context.Context) error {
s.mu.Lock()
s.started = false
image := s.builtImage
s.builtImage = ""
s.mu.Unlock()
if image == "" {
image = tempDockerImageName(s.id)
}
removeDockerSandbox(ctx, s.name, image)
return nil
}
// removeDockerSandbox drops a sandbox container. Per-run throwaway images
// (agentflow-tmp-*) are removed with it; content-hashed cache images stay so
// the next SOP with the same Dockerfile does not rebuild from node:22.
func removeDockerSandbox(ctx context.Context, container, image string) {
if !dockerAvailable() {
return
}
// Retry holds the engine state mutex across this call, so an unresponsive
// daemon must not be able to block it indefinitely. rm -f is a SIGKILL and
// the sweep retries every 20s, so giving up early costs nothing.
ctx, cancel := context.WithTimeout(ctx, dockerTeardownTimeout)
defer cancel()
if strings.TrimSpace(container) != "" {
_ = removeDockerWorkspaceContainers(ctx, container)
}
if ephemeralDockerImage(image) {
_ = exec.CommandContext(ctx, "docker", "rmi", "-f", image).Run()
}
}
const (
dockerTeardownTimeout = 60 * time.Second
legacyDockerScriptSuffix = "-scripts"
)
func removeDockerWorkspaceContainers(ctx context.Context, container string) error {
// Older runs can still own a script companion. Reclaim it with the workspace.
if err := removeDockerContainer(ctx, container+legacyDockerScriptSuffix); err != nil {
return err
}
removeDockerBrowser(ctx, container)
return removeDockerContainer(ctx, container)
}
func removeDockerContainer(ctx context.Context, name string) error {
out, err := exec.CommandContext(ctx, "docker", "rm", "-f", name).CombinedOutput()
if err != nil && !dockerObjectGone(string(out), err) {
return fmt.Errorf("remove Docker container %s: %w: %s", name, err, strings.TrimSpace(string(out)))
}
return nil
}
// dockerAvailable keeps run teardown from spawning processes on control planes
// that only ever use the local driver. Cleanup runs per finished run and on a
// 20s sweep, so this is on a hot path.
var dockerAvailable = sync.OnceValue(func() bool {
_, err := exec.LookPath("docker")
return err == nil
})
var dockerReady struct {
sync.Mutex
checked time.Time
ok bool
}
// DockerReady reports whether the Docker daemon answers, cached for a minute
// because the UI asks on every page load.
func DockerReady() bool {
dockerReady.Lock()
defer dockerReady.Unlock()
if time.Since(dockerReady.checked) < time.Minute {
return dockerReady.ok
}
ok := false
if dockerAvailable() {
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
ok = exec.CommandContext(ctx, "docker", "version", "--format", "{{.Server.Version}}").Run() == nil
cancel()
}
dockerReady.checked, dockerReady.ok = time.Now(), ok
return ok
}
func (s *dockerSandbox) Exec(ctx context.Context, command CommandSpec, sink EventSink) (string, error) {
if err := s.ensureStarted(ctx); err != nil {
return "", err
}
s.execGate.RLock()
out, err := s.execOnce(ctx, command, sink)
s.execGate.RUnlock()
if err != nil && isDockerCwdUnsafe(out, err) {
s.execGate.Lock()
recErr := s.Recreate(ctx)
s.execGate.Unlock()
if recErr != nil {
return out, fmt.Errorf("current working directory is outside of container mount namespace: %w", err)
}
s.execGate.RLock()
out, err = s.execOnce(ctx, command, sink)
s.execGate.RUnlock()
if err != nil && isDockerCwdUnsafe(out, err) {
return out, fmt.Errorf("current working directory is outside of container mount namespace: %w", err)
}
}
// docker CLI reports "No such exec instance" on stderr and exits 1.
// The engine only sees `exit status 1` unless that daemon line is kept
// on the error; Recreate here would docker rm a still-bound workspace.
if err != nil {
err = annotateDockerExecError(out, err)
if isMissingDockerExec(err) {
s.invalidate()
}
}
return out, err
}
func (s *dockerSandbox) execOnce(ctx context.Context, command CommandSpec, sink EventSink) (out string, err error) {
command, cliPath, err := s.prepareSOPCLI(ctx, command)
if err != nil {
return "", err
}
args := []string{"exec"}
if command.Stdin != nil || isManagedClaude(command) {
args = append(args, "-i")
}
for _, environment := range appendEnvironment(nil, s.profile.Environment, command.environment) {
args = append(args, "-e", environment)
}
if cliPath != "" {
args = append(args, "-e", "AGENTFLOW_RUNTIME_CLI_PATH="+cliPath)
}
toolchain := s.toolchainExecEnv()
args = append(args, toolchain...)
args = append(args, s.name)
argv := dockerWorkspaceExecArgv(command.Argv)
if command.WorkingDir != "" {
argv = append([]string{"sh", "-lc", dockerMCPCallLaunch + dockerCLISharedPathSetup +
`cd "$1" && shift && exec "$@"`, "conversation", command.WorkingDir}, dropShellLoginFlag(command.Argv)...)
}
processFile := ""
if command.OwnProcessGroup {
processFile = filepath.Join(s.requirements.ConversationRoot, "home", "tmp", fmt.Sprintf("process-%d.pid", time.Now().UnixNano()))
argv = dockerConversationProcessArgv(processFile, argv)
defer func() {
stopCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
stopArgs := append(append(append([]string{"exec"}, toolchain...), s.name), dockerConversationStopArgv(processFile)...)
if stopErr := exec.CommandContext(stopCtx, "docker", stopArgs...).Run(); stopErr != nil {
err = errors.Join(err, fmt.Errorf("停止 CLI 子进程失败: %w", stopErr))
}
}()
}
args = append(args, argv...)
cmd := exec.CommandContext(ctx, "docker", args...)
cmd.Stdin = command.Stdin
return runCommand(cmd, sink, command)
}
// dockerWorkspaceExecArgv runs argv inside /workspace without docker exec -w.
// runc treats a failed getcwd after -w as exit 126 ("cwd outside mount namespace").
// The outer shell is a login shell so the image profile can set php/composer
// PATH; helper bin is prepended after that, and an inner `sh -lc` is demoted
// to `sh -c` so a second login does not wipe the workspace bin.
func dockerWorkspaceExecArgv(argv []string) []string {
launch := dockerMCPCallLaunch + "PATH=$PATH:" + dockerCLISharedPath + "\nexport PATH\n"
if len(argv) == 0 {
return []string{"sh", "-lc", launch + "pwd"}
}
return append([]string{"sh", "-lc", launch + `exec "$0" "$@"`}, dropShellLoginFlag(argv)...)
}
const dockerMCPCallLaunch = `cd /workspace || exit
if [ -x /workspace/.agentflow/runtime/bin/agentflow-helper ]; then
PATH=/workspace/.agentflow/runtime/bin:$PATH
export PATH
fi
if [ -n "${AGENTFLOW_RUNTIME_CLI_PATH:-}" ] && [ -d "$AGENTFLOW_RUNTIME_CLI_PATH" ]; then
PATH=$PATH:$AGENTFLOW_RUNTIME_CLI_PATH
export PATH
fi
` + toolchainPathSetup
// prepareSOPCLI is limited to the default binaries of registered providers.
// Explicit executable paths, shell tasks and already prepared chat commands
// retain their original argv.
func (s *dockerSandbox) prepareSOPCLI(ctx context.Context, command CommandSpec) (CommandSpec, string, error) {
spec, ok := onDemandCLICatalog()[command.Provider]
if !ok || len(command.Argv) == 0 || command.Argv[0] != spec.Binary {
return command, "", nil
}
// Probe with the normal command user's PATH. This also finds installs
// from earlier nodes without running the privileged preparation again.
args := []string{"exec"}
path, hasPath := command.environment["PATH"]
if !hasPath {
path, hasPath = s.profile.Environment["PATH"]
}
if hasPath {
args = append(args, "-e", "PATH="+path)
}
args = append(append(args, s.toolchainExecEnv()...), s.name)
args = append(args, dockerWorkspaceExecArgv([]string{"sh", "-c", dockerCLIProbe, "loopforge-cli-probe", spec.Binary})...)
output, err := exec.CommandContext(ctx, "docker", args...).CombinedOutput()
if err == nil {
return command, "", nil
}
if !isDockerCLIMissing(err) {
return command, "", fmt.Errorf("探测沙箱 CLI %s 失败:%w: %s", spec.Binary, err, conversationSetupOutput(output))
}
// The published image can use the existing, shared host installations.
// Other sandboxes prepare the official CLI in the current container.
cliPath, err := s.onDemandCLIPath(ctx, command)
if err != nil || cliPath != "" {
return command, cliPath, err
}
binary, err := s.ensureDockerCLI(ctx, command.Provider, "/workspace")
if err != nil {
return command, "", err
}
command.Argv = append([]string{binary}, command.Argv[1:]...)
return command, "", nil
}
func isDockerCLIMissing(err error) bool {
var exit *exec.ExitError
return errors.As(err, &exit) && exit.ExitCode() == 127
}
// onDemandCLIPath installs a CLI the published runtime image does not bundle
// (Claude Code and the npm agent CLIs) for sandboxes of that image, and returns
// the mounted bin directory. It is appended to PATH so a CLI shipped by an
// older image still takes precedence.
func (s *dockerSandbox) onDemandCLIPath(ctx context.Context, command CommandSpec) (string, error) {
if len(command.Argv) == 0 || RuntimeCLIDir() == "" || isolatedRuntimeImage(s.dockerfile) == "" {
return "", nil
}
spec, ok := onDemandCLICatalog()[command.Provider]
if !ok || spec.Bundled || spec.Script != "" || command.Argv[0] != spec.Binary {
return "", nil
}
if spec.Engine == "claude-code" {
if _, err := EnsureClaudeCode(ctx); err != nil {
return "", err
}
return ClaudeCodeBinDir(), nil
}
path, err := InstallOnDemandCLI(ctx, spec.Engine)
if err != nil {
return "", err
}
return filepath.Dir(path), nil
}
func dropShellLoginFlag(argv []string) []string {
if len(argv) == 0 {
return argv
}
switch filepath.Base(argv[0]) {
case "sh", "bash", "dash", "zsh":
default:
return argv
}
out := []string{argv[0]}
for _, arg := range argv[1:] {
switch arg {
case "-lc", "-cl":
out = append(out, "-c")
case "-l", "--login":
continue
default:
out = append(out, arg)
}
}
return out
}
func (s *dockerSandbox) Recreate(ctx context.Context) error {
return s.start(ctx, true)
}
// invalidate drops the cached started flag without docker rm. The next
// ensureStarted revalidates: a live container on the same workspace bind is
// restarted and reused, and only a genuinely broken one gets recreated.
func (s *dockerSandbox) invalidate() {
s.mu.Lock()
s.started = false
s.mu.Unlock()
}
// BindWorkspace starts the container against the current workspace inode.
// Unlike Recreate, a healthy container started after checkout is reused so
// later nodes and retries do not docker rm a live bind.
func (s *dockerSandbox) BindWorkspace(ctx context.Context) error {
return s.ensureStarted(ctx)
}
func IsCwdMountFailure(err error) bool {
return isDockerCwdUnsafe("", err)
}
// IsSandboxInterrupt reports deploy/restart teardown: context cancel, a
// SIGTERM'd helper, or Docker destroying the exec/container underneath us.
// These must park the node for resume instead of consuming MaxAttempts.
func IsSandboxInterrupt(err error) bool {
if err == nil {
return false
}
if errors.Is(err, context.Canceled) {
return true
}
msg := strings.ToLower(err.Error())
return strings.Contains(msg, "context canceled") ||
strings.Contains(msg, "signal: killed") ||
strings.Contains(msg, "signal: terminated") ||
isMissingDockerExec(err)
}
func isMissingDockerExec(err error) bool {
if err == nil {
return false
}
return looksLikeDockerExecGone(err.Error())
}
func looksLikeDockerExecGone(text string) bool {
msg := strings.ToLower(text)
return strings.Contains(msg, "no such exec instance") ||
strings.Contains(msg, "no such container") ||
strings.Contains(msg, "container not found") ||
(strings.Contains(msg, "error response from daemon") && strings.Contains(msg, "is not running"))
}
func annotateDockerExecError(out string, err error) error {
if err == nil || looksLikeDockerExecGone(err.Error()) {
return err
}
excerpt := dockerInterruptExcerpt(out)
if excerpt == "" {
return err
}
return fmt.Errorf("%w: %s", err, excerpt)
}
// dockerInterruptExcerpt returns the docker CLI's own failure line from the
// tail of out. Everything else in out is agent-controlled text, and an
// interrupt parks the node without consuming an attempt, so a build log that
// merely mentions "no such container" must not be able to requeue forever.
func dockerInterruptExcerpt(out string) string {
lines := strings.Split(strings.TrimRight(out, "\n"), "\n")
if len(lines) > dockerInterruptTailLines {
lines = lines[len(lines)-dockerInterruptTailLines:]
}
for _, line := range lines {
line = strings.TrimSpace(line)
lower := strings.ToLower(line)
if !strings.HasPrefix(lower, "error response from daemon:") && !strings.HasPrefix(lower, "error: no such") {
continue
}
if !looksLikeDockerExecGone(lower) {
continue
}
if len(line) > 300 {
return line[:300]
}
return line
}
return ""
}
const dockerInterruptTailLines = 5
func isDockerCwdUnsafe(out string, err error) bool {
if err == nil {
return false
}
msg := strings.ToLower(out + "\n" + err.Error())
return strings.Contains(msg, "outside of container mount") || strings.Contains(msg, "container breakout") || strings.Contains(msg, "oci runtime exec failed") || strings.Contains(msg, "exit status 126")
}
type dockerWorkspaceMounts struct {
source string
legacyMasks bool
}
func inspectDockerWorkspaceMounts(ctx context.Context, name string) (*dockerWorkspaceMounts, error) {
out, err := exec.CommandContext(ctx, "docker", "inspect", "--type", "container", "--format", `{{json .Mounts}}`, name).CombinedOutput()
if dockerObjectGone(string(out), err) {
return nil, nil
}
if err != nil {
return nil, fmt.Errorf("docker inspect mounts: %w: %s", err, strings.TrimSpace(string(out)))
}
var mounts []struct {
Destination, Source string
}
if err := json.Unmarshal(out, &mounts); err != nil {
return nil, fmt.Errorf("decode Docker mounts for %s: %w", name, err)
}
workspace := &dockerWorkspaceMounts{}
for _, mount := range mounts {
switch mount.Destination {
case "/workspace":
workspace.source = mount.Source
case "/workspace/.agentflow/isolation/empty-dir", "/workspace/.agentflow/isolation/empty-file":
// Older containers keep these binds even when restarted.
workspace.legacyMasks = true
}
}
return workspace, nil
}
func dockerBindMatchesWorkspace(source, workspace string) bool {
if strings.TrimSpace(source) == "" || strings.TrimSpace(workspace) == "" {
return false
}
want, err := filepath.Abs(workspace)
if err != nil {
return false
}
got, err := filepath.Abs(source)
if err != nil {
return false
}
return filepath.Clean(got) == filepath.Clean(want)
}
// dockerSandboxesUnder maps sandbox container name -> workspace directory name
// for every container whose /workspace bind lives directly under root.
//
// Ownership is decided by the bind mount, not by the name, because a runner
// daemon sharing the host creates agentflow-rt-* containers against its own
// workspace root and cleans them up itself.
func dockerSandboxesUnder(ctx context.Context, root string) (map[string]string, error) {
if !dockerAvailable() {
return nil, nil
}
absRoot, err := filepath.Abs(root)
if err != nil {
return nil, err
}
ids, err := exec.CommandContext(ctx, "docker", "ps", "-aq", "--filter", "name=^/"+dockerSandboxPrefix).Output()
if err != nil {
return nil, fmt.Errorf("docker ps: %w", err)
}
out, err := collectDockerSandboxMounts(ctx, strings.Fields(string(ids)))
if err != nil {
return nil, err
}
return parseDockerSandboxMounts(out, absRoot), nil
}
// dockerSandboxMountFormat is one inspect line: container name, tab, the host
// path bound at /workspace.
const dockerSandboxMountFormat = `{{.Name}}` + "\t" + `{{range .Mounts}}{{if eq .Destination "/workspace"}}{{.Source}}{{end}}{{end}}`
// collectDockerSandboxMounts inspects each container on its own. A container
// that disappears between ps and inspect is skipped; one failure used to abort
// the whole reclaim pass.
func collectDockerSandboxMounts(ctx context.Context, ids []string) (string, error) {
var b strings.Builder
for _, id := range ids {
out, err := exec.CommandContext(ctx, "docker", "inspect", "-f", dockerSandboxMountFormat, id).CombinedOutput()
if err != nil {
if dockerObjectGone(string(out), err) {
continue
}
return "", fmt.Errorf("docker inspect %s: %w: %s", id, err, strings.TrimSpace(string(out)))
}
line := strings.TrimSpace(string(out))
if line == "" {
continue
}
b.WriteString(line)
b.WriteByte('\n')
}
return b.String(), nil
}
func dockerObjectGone(output string, err error) bool {
if err == nil {
return false
}
msg := strings.ToLower(output + "\n" + err.Error())
return strings.Contains(msg, "no such object") ||
strings.Contains(msg, "no such container") ||
strings.Contains(msg, "container not found")
}
// parseDockerSandboxMounts reads `docker inspect` lines of "name\tbindSource"
// and keeps only the containers bound one level under root.
func parseDockerSandboxMounts(out, absRoot string) map[string]string {
found := map[string]string{}
for _, line := range strings.Split(strings.TrimSpace(out), "\n") {
name, source, ok := strings.Cut(strings.TrimSpace(line), "\t")
name = strings.TrimPrefix(strings.TrimSpace(name), "/")
source = strings.TrimSpace(source)
if !ok || name == "" || source == "" {
continue
}
abs, err := filepath.Abs(source)
if err != nil || filepath.Dir(abs) != absRoot {
continue
}
found[name] = filepath.Base(abs)
}
return found
}
func createDocker(ctx context.Context, id, workspace string, p domain.SandboxProfile, requirements SandboxRequirements, dockerfile domain.DockerfileDefinition) (Sandbox, error) {
if strings.TrimSpace(dockerfile.Content) == "" {
return nil, fmt.Errorf("docker sandbox requires a dockerfile")
}
// Delay docker create until the first Exec so the bind-mount is taken
// after prepareRepository has cloned into this directory. Creating the
// container first, then letting git replace the workspace inode, is the
// runc 126 "cwd outside mount namespace" failure.
return &dockerSandbox{id: id, name: dockerContainerName(id), workspace: workspace, profile: p, requirements: requirements, dockerfile: dockerfile}, nil
}
const dockerSandboxPrefix = "agentflow-"
const dockerCachedImagePrefix = "agentflow-img-"
const dockerTempImagePrefix = "agentflow-tmp-"
func dockerContainerName(id string) string { return dockerSandboxPrefix + id }
func tempDockerImageName(id string) string { return dockerTempImagePrefix + safeID(id) }
func ephemeralDockerImage(image string) bool {
return strings.HasPrefix(strings.TrimSpace(image), dockerTempImagePrefix)
}
func dropEphemeralDockerImage(image string) {
if !ephemeralDockerImage(image) {
return
}
_ = exec.Command("docker", "rmi", "-f", image).Run()
}
func cachedDockerImageName(dockerfile domain.DockerfileDefinition) string {
sum := sha256.Sum256(dockerImageCacheKey(dockerfile))
return dockerCachedImagePrefix + hex.EncodeToString(sum[:])[:16]
}
func dockerImageCacheKey(dockerfile domain.DockerfileDefinition) []byte {
var b strings.Builder
b.WriteString(dockerfile.Content)
b.WriteByte(0)
names := make([]string, 0, len(dockerfile.Files))
for name := range dockerfile.Files {
names = append(names, name)
}
sort.Strings(names)
for _, name := range names {
b.WriteString(name)
b.WriteByte(0)
b.WriteString(dockerfile.Files[name])
b.WriteByte(0)
}
return []byte(b.String())
}
func dockerImageExists(ctx context.Context, image string) bool {
if strings.TrimSpace(image) == "" || !dockerAvailable() {
return false
}
return exec.CommandContext(ctx, "docker", "image", "inspect", image).Run() == nil
}
// DockerImageCached reports whether this Dockerfile already has a local cache
// tag. Used by the engine to tell first-run users that a long image build is
// about to start, instead of looking like the node never began.
func DockerImageCached(ctx context.Context, dockerfile domain.DockerfileDefinition) bool {
if strings.TrimSpace(dockerfile.Content) == "" {
return false
}
if image := isolatedRuntimeImage(dockerfile); image != "" {
return dockerImageExists(ctx, image)
}
return dockerImageExists(ctx, cachedDockerImageName(dockerfile))
}
func reclaimCachedDockerImages(ctx context.Context, keep map[string]struct{}) (int, error) {
listed, err := listCachedDockerImages(ctx)
if err != nil {
return 0, err
}
inUse, err := cachedDockerImagesInUse(ctx)
if err != nil {
return 0, err
}
removed := 0
for _, image := range staleCachedDockerImages(listed, keep, inUse) {
if out, err := exec.CommandContext(ctx, "docker", "rmi", "-f", image).CombinedOutput(); err != nil {
return removed, fmt.Errorf("docker rmi %s: %w: %s", image, err, strings.TrimSpace(string(out)))
}
removed++
}
return removed, nil
}
func listCachedDockerImages(ctx context.Context) ([]string, error) {
out, err := exec.CommandContext(ctx, "docker", "images", "--format", "{{.Repository}}", "--filter", "reference="+dockerCachedImagePrefix+"*").Output()
if err != nil {
return nil, fmt.Errorf("docker images: %w: %s", err, strings.TrimSpace(string(out)))
}
return parseCachedDockerImageNames(string(out)), nil
}
func cachedDockerImagesInUse(ctx context.Context) (map[string]struct{}, error) {
out, err := exec.CommandContext(ctx, "docker", "ps", "-a", "--format", "{{.Image}}").Output()
if err != nil {
return nil, fmt.Errorf("docker ps: %w: %s", err, strings.TrimSpace(string(out)))
}
used := map[string]struct{}{}
for _, image := range parseCachedDockerImageNames(string(out)) {
used[image] = struct{}{}
}
return used, nil
}
func parseCachedDockerImageNames(out string) []string {
var names []string
seen := map[string]struct{}{}
for _, line := range strings.Split(out, "\n") {
name := normalizeCachedDockerImageName(line)
if name == "" {
continue
}
if _, ok := seen[name]; ok {
continue
}
seen[name] = struct{}{}
names = append(names, name)
}
return names
}
func normalizeCachedDockerImageName(raw string) string {
name := strings.TrimSpace(raw)
if name == "" {
return ""
}
if tag := strings.LastIndex(name, ":"); tag > 0 && !strings.Contains(name[tag:], "/") {
name = name[:tag]
}
if !strings.HasPrefix(name, dockerCachedImagePrefix) {
return ""
}
return name
}
func staleCachedDockerImages(listed []string, keep, inUse map[string]struct{}) []string {
var stale []string
for _, image := range listed {
if !strings.HasPrefix(image, dockerCachedImagePrefix) {
continue
}
if _, ok := keep[image]; ok {
continue
}
if _, ok := inUse[image]; ok {
continue
}
stale = append(stale, image)
}
return stale
}
func (s *dockerSandbox) ensureStarted(ctx context.Context) error {
return s.start(ctx, false)
}
func (s *dockerSandbox) start(ctx context.Context, recreate bool) error {
s.mu.Lock()
defer s.mu.Unlock()
if s.started && !recreate {
return nil
}
s.started = false
name, workspace, p := s.name, s.workspace, s.profile
mounts, err := inspectDockerWorkspaceMounts(ctx, name)
if err != nil {
return err
}
if mounts != nil {
if !dockerBindMatchesWorkspace(mounts.source, workspace) {
return fmt.Errorf("docker sandbox %s is bound to %s, not %s", name, mounts.source, workspace)
}
if !recreate && !mounts.legacyMasks {
if err := exec.CommandContext(ctx, "docker", "start", name).Run(); err == nil {
if err := waitDockerWorkspaceReady(ctx, name); err == nil {
s.started = true
return nil
}
}
}
}
built, err := ensureDockerImage(ctx, workspace, s.dockerfile)
if err != nil {
return err
}
image := built
args := []string{"create", "--name", name, "--init", "--cap-drop=ALL", "--security-opt", "no-new-privileges", "-v", workspace + ":/workspace"}
// Native installs own private (0700) workspaces as the service user.
// A root image without DAC capabilities cannot access another UID's bind.
// Run default/root images as that user; retain explicit non-root image users.
if os.Geteuid() != 0 {
configured, err := exec.CommandContext(ctx, "docker", "image", "inspect", "--format", "{{.Config.User}}", image).CombinedOutput()
if err != nil {
return fmt.Errorf("inspect sandbox image user: %w: %s", err, strings.TrimSpace(string(configured)))
}
user, _, _ := strings.Cut(strings.TrimSpace(string(configured)), ":")
if user == "" || user == "root" || user == "0" {
args = append(args, "--user", fmt.Sprintf("%d:%d", os.Geteuid(), os.Getegid()))
}
}
network := strings.TrimSpace(os.Getenv("AGENTFLOW_DOCKER_NETWORK"))
if s.requirements.ConversationRoot != "" || s.requirements.RunnerLoginRelay {
_, relayNetwork, err := conversationDockerAccess(ctx)
if err != nil {
return err
}
if relayNetwork != "" {
network = relayNetwork
}
args = append(args, "--add-host", "host.docker.internal:host-gateway")
}
if network != "" {
args = append(args, "--network", network)
}
if root := s.requirements.ConversationRoot; root != "" {
args = append(args, "-v", root+":"+root+":ro", "-v", filepath.Join(root, "home")+":"+filepath.Join(root, "home"), "-v", workspace+":"+filepath.Join(root, "ws"))
guards, err := conversationGuardMounts(root)
if err != nil {
return err
}
args = append(args, guards...)
}
stateArgs, err := dockerAgentStateMountRequirements(s.requirements)
if err != nil {
return err
}
args = append(args, stateArgs...)
if cliDir := RuntimeCLIDir(); cliDir != "" {
if err := os.MkdirAll(cliDir, 0o755); err != nil {
return fmt.Errorf("prepare runtime CLI directory: %w", err)
}
args = append(args, "--mount", "type=bind,src="+cliDir+",dst="+cliDir+",readonly")
}
if p.ReadOnlyRootFS {
args = append(args, "--read-only", "--tmpfs", "/tmp:rw,noexec,nosuid,size=256m")
}
if image == isolatedRuntimeImage(s.dockerfile) {
args = append(args, "--entrypoint", "sh", image, "-lc", "trap : TERM INT; sleep infinity & wait")
} else {
args = append(args, image, "sh", "-lc", "trap : TERM INT; sleep infinity & wait")
}
// Resolve the replacement image and mounts before retiring a workspace with
// legacy masks. Its new container ID invalidates old preparation receipts.
if mounts != nil || recreate {
if err := removeDockerWorkspaceContainers(ctx, name); err != nil {
return err
}
}
s.builtImage = built
if out, err := exec.CommandContext(ctx, "docker", args...).CombinedOutput(); err != nil {
dropEphemeralDockerImage(s.builtImage)
s.builtImage = ""
return fmt.Errorf("docker create: %w: %s", err, out)
}
if out, err := exec.CommandContext(ctx, "docker", "start", name).CombinedOutput(); err != nil {
_ = exec.CommandContext(ctx, "docker", "rm", "-f", name).Run()
dropEphemeralDockerImage(s.builtImage)
s.builtImage = ""
return fmt.Errorf("docker start: %w: %s", err, out)
}
if err := waitDockerWorkspaceReady(ctx, name); err != nil {
_ = exec.Command("docker", "rm", "-f", name).Run()
s.started = false
return err
}
s.started = true
return nil
}
func waitDockerWorkspaceReady(ctx context.Context, name string) error {
deadline := time.Now().Add(20 * time.Second)
var lastOut []byte
var lastErr error
for {
cmd := exec.CommandContext(ctx, "docker", "exec", name, "sh", "-lc", "cd /workspace && pwd")
lastOut, lastErr = cmd.CombinedOutput()
if lastErr == nil && strings.Contains(string(lastOut), "/workspace") {
return nil
}
if ctx.Err() != nil {
return ctx.Err()
}
if time.Now().After(deadline) {
if lastErr == nil {
lastErr = fmt.Errorf("unexpected pwd output %q", strings.TrimSpace(string(lastOut)))
}
return fmt.Errorf("docker workspace not ready: %w: %s", lastErr, strings.TrimSpace(string(lastOut)))
}
time.Sleep(200 * time.Millisecond)
}
}
func dockerBuildArgs(image, contextDir string) []string {
return []string{"build", "-t", image, contextDir}
}
func prepareDockerfileBuildContext(workspace string, dockerfile domain.DockerfileDefinition) (string, error) {
if strings.TrimSpace(dockerfile.Content) == "" {
return "", fmt.Errorf("dockerfile content is empty")
}
contextID, err := catalogDirName(dockerfile.ID)
if err != nil {
contextID = "default"
}
root, err := resetControlDirectory(workspace, "docker", contextID)
if err != nil {
return "", err
}
if err := writeManagedFile(workspace, filepath.Join(root, "Dockerfile"), []byte(dockerfile.Content), 0o600); err != nil {
return "", err
}
for name, data := range dockerfile.Files {
if err := domain.ValidateRelativeFilePath(name); err != nil {
return "", fmt.Errorf("dockerfile file: %w", err)
}
if filepath.Base(name) == "Dockerfile" && filepath.Dir(filepath.FromSlash(name)) == "." {
continue
}
target := filepath.Join(root, filepath.FromSlash(filepath.Clean(name)))
rel, relErr := filepath.Rel(root, target)
if relErr != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(os.PathSeparator)) {
return "", fmt.Errorf("invalid dockerfile file path %q", name)
}
if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil {
return "", err
}
if err := writeManagedFile(workspace, target, []byte(data), 0o644); err != nil {
return "", err
}
}
return root, nil
}
func ensureDockerImage(ctx context.Context, workspace string, dockerfile domain.DockerfileDefinition) (string, error) {
if image := isolatedRuntimeImage(dockerfile); image != "" {
if !dockerImageExists(ctx, image) {
return "", fmt.Errorf("isolated runtime image %q is not available in the sandbox Docker daemon", image)
}
return image, nil
}
image := cachedDockerImageName(dockerfile)
if dockerImageExists(ctx, image) {
return image, nil
}
contextDir, err := prepareDockerfileBuildContext(workspace, dockerfile)
if err != nil {
return "", err
}
args := dockerBuildArgs(image, contextDir)
build := func(ctx context.Context) *exec.Cmd { return exec.CommandContext(ctx, "docker", args...) }
if tail, err := procwatch.Run(ctx, build, dockerBuildWatch(dockerfile)); err != nil {
// Only the tail: a build killed after minutes of apt output used to
// carry all of it in the error.
return "", fmt.Errorf("docker build: %w: %s", err, tail)
}
return image, nil
}
// Build limits. A RUN step can be silent for a while (a compile, a large
// download without a progress bar), so the stall window is wider than for git.
const (
dockerBuildStallEnv = "AGENTFLOW_DOCKER_BUILD_STALL_TIMEOUT"
dockerBuildTimeoutEnv = "AGENTFLOW_DOCKER_BUILD_TIMEOUT"
)
func dockerBuildWatch(dockerfile domain.DockerfileDefinition) procwatch.Options {
name := strings.TrimSpace(dockerfile.Name)
if name == "" {
name = strings.TrimSpace(dockerfile.ID)
}
label := "构建沙箱镜像"
if name != "" {
label += " " + name
}
return procwatch.Options{
Stage: "image", Label: label,
Stall: procwatch.DurationEnv(dockerBuildStallEnv, 10*time.Minute), StallEnv: dockerBuildStallEnv,
Timeout: procwatch.DurationEnv(dockerBuildTimeoutEnv, 0), TimeoutEnv: dockerBuildTimeoutEnv,
}
}
func isolatedRuntimeImage(dockerfile domain.DockerfileDefinition) string {
if dockerfile.Content != IsolatedDockerfile || len(dockerfile.Files) != 0 {
return ""
}
return strings.TrimSpace(os.Getenv("AGENTFLOW_ISOLATED_IMAGE"))
}
// IsolatedDockerfile matches the public "generic-backend" environment so both
// share one cached image.
const IsolatedDockerfile = "FROM node:22-bookworm\nRUN apt-get update && apt-get install -y --no-install-recommends git openssh-client python3 ripgrep ca-certificates curl && rm -rf /var/lib/apt/lists/*\nRUN npm install -g @openai/codex @anthropic-ai/claude-code @tencent-ai/codebuddy-code\nWORKDIR /workspace\n"
// PrebuildIsolatedImage warms the shared sandbox image in the background so
// the first SOP on a fresh container install does not wait for the build.
func PrebuildIsolatedImage() {
if strings.TrimSpace(os.Getenv("AGENTFLOW_LOCAL_SANDBOX")) != "docker" || !DockerReady() {
return
}
go func() {
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Minute)
defer cancel()
dir, err := os.MkdirTemp("", "agentflow-prebuild-")
if err != nil {
return
}
defer os.RemoveAll(dir)
if _, err := ensureDockerImage(ctx, dir, domain.DockerfileDefinition{ID: "isolated", Content: IsolatedDockerfile}); err != nil {
log.Printf("prebuild sandbox image: %v", err)
}
}()
}
// isolateLocalDriver runs "local" profiles in Docker when
// AGENTFLOW_LOCAL_SANDBOX=docker, so no SOP command executes inside a platform
// container that can reach the host Docker daemon.
func isolateLocalDriver(profile domain.SandboxProfile, dockerfile domain.DockerfileDefinition) (domain.SandboxProfile, domain.DockerfileDefinition) {
driver := strings.TrimSpace(profile.Driver)
if (driver != "" && driver != "local") || strings.TrimSpace(os.Getenv("AGENTFLOW_LOCAL_SANDBOX")) != "docker" {
return profile, dockerfile
}
profile.Driver = "docker"
if strings.TrimSpace(dockerfile.Content) == "" {
dockerfile = domain.DockerfileDefinition{ID: "generic-backend", Name: "Isolated local sandbox", Content: IsolatedDockerfile}
}
return profile, dockerfile
}