Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/deployment.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,8 @@ For native services running as an ordinary host user, default/root Docker images

The Compose deployment mounts the host Docker socket into the platform container so built-in AI SOPs run out of the box. `AGENTFLOW_ISOLATED_IMAGE` points to the installed platform image: default sandboxes start separate sibling containers from that same image, with no second CLI download or image build. They do not mount the Docker socket. Custom Dockerfiles still build and cache their own images. The run workspace is mounted at `/workspace` on the Compose network. Because bind mounts are resolved by the host Docker daemon, `LOOPFORGE_DATA_DIR` (written to `.env` by `scripts/configure.sh`, default `./.data`) is mounted into the platform container at the same absolute path; workspaces and CLI state live under it. Native conversation workspaces bind-mount their conversation roots the same way, so `compose.yaml` sets `AGENTFLOW_CONVERSATION_DIR` to `${LOOPFORGE_DATA_DIR}/conversations`. Conversation workspaces in a Compose deployment use Docker sandboxes: the native (bwrap) sandbox needs user and PID namespaces, which the unprivileged platform container cannot create, and the image does not ship bubblewrap. Use a native installation or a connected execution machine for native sandboxes. Attachments and other per-user assistant state stay in `AGENTFLOW_ASSISTANT_SESSION_DIR` (`/data/assistant` in the `platform-data` volume), which is never mounted into a workspace. A platform container whose `AGENTFLOW_CONVERSATION_DIR` is unset keeps conversation roots there too, and opening a conversation workspace then fails with `mkdirat ... read-only file system`.

Docker SOP nodes using a standard CLI executor first look for the CLI on the sandbox user's PATH. When it is missing, LoopForge uses a shared installation for the platform image where available or runs the same installer as conversation workspaces in the container. The install uses the sandbox's configured proxy, and later nodes in that container reuse the CLI. In-container installation requires a writable filesystem and access to the official package source. Read-only sandboxes can use a CLI from the image or the mounted toolchain. ZCode uses the official executable supplied by the image.

Access to the Docker socket is equivalent to root on the host. Two safeguards follow from that: the platform runs every task in a sandbox container, including SOPs configured for the `local` driver (`AGENTFLOW_LOCAL_SANDBOX=docker`), and only platform administrators can point a repository at a host source path. Even so, anyone who can run SOPs can execute code in containers on this host, so only give accounts to people you trust and do not expose the service to untrusted networks. Agent CLIs also apply a bound repository's own configuration as their native rules define, including unattended SOP runs: `AGENTS.md`/`CLAUDE.md` instructions, `.codebuddy/`, `.claude/settings.json` (hooks and environment) and `.mcp.json` can start commands or MCP servers inside the sandbox. Bind only repositories whose contents you trust. To run without the socket, remove the `docker.sock` volume and the `AGENTFLOW_LOCAL_SANDBOX` setting from `compose.yaml`, then connect a separate Docker-capable worker or execution machine for AI SOPs; the script-only welcome SOP then runs inside the platform container.

### Slow networks: clone and image build limits
Expand Down
8 changes: 5 additions & 3 deletions internal/runtime/cli_ondemand.go
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,10 @@ import (
// a person asks from a failed conversation. Package names and installer URLs are fixed:
// the request may choose an engine, never a URL or a package.
const (
cursorInstallScript = "curl -fsSL --proto '=https' --tlsv1.2 https://cursor.com/install | bash"
agyInstallScript = "curl -fsSL --proto '=https' --tlsv1.2 https://antigravity.google/cli/install.sh | bash"
cursorInstallerURL = "https://cursor.com/install"
agyInstallerURL = "https://antigravity.google/cli/install.sh"
cursorInstallScript = "curl -fsSL --proto '=https' --tlsv1.2 " + cursorInstallerURL + " | bash"
agyInstallScript = "curl -fsSL --proto '=https' --tlsv1.2 " + agyInstallerURL + " | bash"
)

// DeepSeekHarnessVersion is the dsh release the Dockerfile bundles and an
Expand All @@ -43,7 +45,7 @@ func onDemandCLICatalog() map[string]onDemandCLI {
return map[string]onDemandCLI{
"codex": {Engine: "codex", Binary: "codex", Package: "@openai/codex", Bundled: true},
"codebuddy": {Engine: "codebuddy", Binary: "codebuddy", Package: "@tencent-ai/codebuddy-code", Bundled: true},
"claude-code": {Engine: "claude-code", Binary: "claude"},
"claude-code": {Engine: "claude-code", Binary: "claude", Package: "@anthropic-ai/claude-code"},
"opencode": {Engine: "opencode", Binary: "opencode", Package: "opencode-ai"},
"cursor": {Engine: "cursor", Binary: "cursor-agent", Script: cursorInstallScript},
"agy": {Engine: "agy", Binary: "agy", Script: agyInstallScript},
Expand Down
43 changes: 43 additions & 0 deletions internal/runtime/cli_ondemand_sandbox_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,54 @@ import (
"context"
"os"
"path/filepath"
"strings"
"testing"

"agentflow/internal/domain"
)

func TestDockerSOPExecInstallsMissingCLIOnce(t *testing.T) {
t.Setenv("AGENTFLOW_RUNTIME_CLI_DIR", "")
setupMarker := filepath.Join(t.TempDir(), "installed")
t.Setenv("LOOPFORGE_TEST_CLI_SETUP", setupMarker)
probes := filepath.Join(t.TempDir(), "probes")
t.Setenv("LOOPFORGE_TEST_CLI_PROBES", probes)
useFakeCommands(t, map[string]string{"docker": `#!/bin/sh
set -eu
case "$*" in
*loopforge-cli-probe*)
printf 'probe\n' >> "$LOOPFORGE_TEST_CLI_PROBES"
test -s "$LOOPFORGE_TEST_CLI_SETUP" || exit 127 ;;
*"id -u; id -g"*) printf '1000\n1000\n' ;;
*loopforge-cli-setup*)
printf 'install\n' >> "$LOOPFORGE_TEST_CLI_SETUP"
printf '/opt/loopforge/conversation-cli/.local/bin/agy\n' ;;
*pwd.getpwuid*) ;;
*) for arg do last=$arg; done
printf '%s\n' "$last" ;;
esac
`})
sandbox := &dockerSandbox{name: "workspace", started: true}
for _, command := range []CommandSpec{
{Provider: AgentCLIAntigravity, Argv: []string{"agy", "first"}},
{Provider: AgentCLIAntigravity, Argv: []string{"agy", "second"}},
{Provider: AgentCLIAntigravity, Argv: []string{"/custom/agy", "explicit"}},
{Provider: "script", Argv: []string{"sh", "-c", "script"}},
} {
want := command.Argv[len(command.Argv)-1]
out, err := sandbox.Exec(context.Background(), command, nil)
if err != nil || strings.TrimSpace(out) != want {
t.Fatalf("exec %v: %q %v", command.Argv, out, err)
}
}
if got, err := os.ReadFile(setupMarker); err != nil || string(got) != "install\n" {
t.Fatalf("expected exactly one setup, got %q: %v", got, err)
}
if got, err := os.ReadFile(probes); err != nil || string(got) != "probe\nprobe\n" {
t.Fatalf("expected probes only for standard CLI invocations, got %q: %v", got, err)
}
}

// A failed on-demand install must stop the sandbox exec instead of silently
// running without the CLI on PATH.
func TestDockerSandboxOnDemandCLIPathReturnsInstallErrors(t *testing.T) {
Expand Down
4 changes: 2 additions & 2 deletions internal/runtime/conversation_approval_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -69,15 +69,15 @@ func TestConversationSupportsEveryRegisteredCLI(t *testing.T) {
if _, err := InstallConversationApproval(root, kind, command); err != nil {
t.Fatal(err)
}
if _, err := conversationCLISetup(kind, conversationBinary(kind)); err != nil {
if _, err := dockerCLISetup(kind, conversationBinary(kind)); err != nil {
t.Fatal(err)
}
})
}
}

func TestZCodeConversationSetupRequiresOfficialPreinstallation(t *testing.T) {
setup, err := conversationCLISetup(AgentCLIZCode, conversationBinary(AgentCLIZCode))
setup, err := dockerCLISetup(AgentCLIZCode, conversationBinary(AgentCLIZCode))
if err != nil || strings.Contains(setup, "npm install") || !strings.Contains(setup, "预装官方 ZCode CLI") {
t.Fatalf("ZCode must use its official preinstalled binary: %s: %v", setup, err)
}
Expand Down
61 changes: 49 additions & 12 deletions internal/runtime/conversation_sandbox.go
Original file line number Diff line number Diff line change
Expand Up @@ -166,13 +166,30 @@ func ensureConversationCLI(ctx context.Context, sandbox Sandbox, provider, home
if !ok {
return "", fmt.Errorf("对话工作区只支持 Docker 或 native 沙箱")
}
s.execGate.RLock()
defer s.execGate.RUnlock()
return s.ensureDockerCLI(ctx, provider, home)
}

// ensureDockerCLI prepares a provider in an existing container. SOP and chat
// callers hold the execution gate so preparation cannot race recreation.
func (s *dockerSandbox) ensureDockerCLI(ctx context.Context, provider, home string) (string, error) {
binary := conversationBinary(provider)
setup, err := conversationCLISetup(provider, binary)
setup, err := dockerCLISetup(provider, binary)
if err != nil {
return "", err
}
ctx, cancel := context.WithTimeout(ctx, 10*time.Minute)
defer cancel()
// npm providers share the same install prefix. Serialize preparation even
// when different SOP nodes start different CLIs in the same container.
s.cliSetupOnce.Do(func() { s.cliSetupGate = make(chan struct{}, 1) })
select {
case s.cliSetupGate <- struct{}{}:
defer func() { <-s.cliSetupGate }()
case <-ctx.Done():
return "", ctx.Err()
}
// Probe the actual execution user, including numeric Docker USER values.
// Root preparation must preserve that identity when the native CLI starts.
identity, err := exec.CommandContext(ctx, "docker", "exec", "--workdir", "/", s.name, "sh", "-c", "id -u; id -g").CombinedOutput()
Expand All @@ -194,7 +211,15 @@ func ensureConversationCLI(ctx context.Context, sandbox Sandbox, provider, home
if err != nil {
return "", err
}
setupArgs := append(append([]string{"exec", "--user", "0:0", "--workdir", "/"}, toolchain...), s.name, "sh", "-lc", setup, "loopforge-cli-setup", ids[0], ids[1], home)
setupArgs := []string{"exec", "--user", "0:0", "--workdir", "/"}
// Preparation uses a separate Docker exec as root. Carry the sandbox's
// configured network settings into that exec as well as normal CLI turns.
for _, key := range []string{"HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", "NO_PROXY", "http_proxy", "https_proxy", "all_proxy", "no_proxy"} {
if value, ok := s.profile.Environment[key]; ok {
setupArgs = append(setupArgs, "-e", key+"="+value)
}
}
setupArgs = append(append(setupArgs, toolchain...), s.name, "sh", "-lc", setup, "loopforge-cli-setup", ids[0], ids[1], home)
output, err := exec.CommandContext(ctx, "docker", setupArgs...).CombinedOutput()
if err != nil {
return "", fmt.Errorf("准备 %s 原生CLI失败(工作区镜像需支持 Node.js/npm 和 Python3):%w: %s", provider, err, conversationSetupOutput(output))
Expand All @@ -211,28 +236,25 @@ func ensureConversationCLI(ctx context.Context, sandbox Sandbox, provider, home
return path, nil
}

func conversationCLISetup(provider, binary string) (string, error) {
packages := map[string]string{
"codebuddy": "@tencent-ai/codebuddy-code", "codex": "@openai/codex", "claude-code": "@anthropic-ai/claude-code",
AgentCLIOpenCode: "opencode-ai", AgentCLIKimi: "@moonshot-ai/kimi-code", AgentCLIPi: "@earendil-works/pi-coding-agent", AgentCLIDeepSeek: "@deepseek-ai/dsh@" + DeepSeekHarnessVersion,
}
func dockerCLISetup(provider, binary string) (string, error) {
spec := onDemandCLICatalog()[provider]
installer := ""
if pkg := packages[provider]; pkg != "" {
if spec.Package != "" {
flags := ""
if provider == AgentCLIDeepSeek {
if spec.RelaxEngines {
flags = "--engine-strict=false "
}
installer = "npm install --no-audit --no-fund " + flags + "--prefix /opt/loopforge/conversation-cli " + shellSingleQuote(pkg) + " >&2\nln -sf ../node_modules/.bin/" + shellSingleQuote(binary) + " /opt/loopforge/conversation-cli/bin/" + shellSingleQuote(binary)
installer = "npm install --no-audit --no-fund " + flags + "--prefix /opt/loopforge/conversation-cli " + shellSingleQuote(spec.Package) + " >&2\nln -sf ../node_modules/.bin/" + shellSingleQuote(binary) + " /opt/loopforge/conversation-cli/bin/" + shellSingleQuote(binary)
} else {
switch provider {
case AgentCLIZCode:
// The official CLI is shipped with ZCode or built from its source;
// it has no standalone npm package. Never install a namesake.
installer = "echo 'ZCode CLI 未安装;请在工作区镜像中预装官方 ZCode CLI 并将 zcode 加入 PATH' >&2; exit 1"
case AgentCLICursor:
installer = "curl -fsSL https://cursor.com/install | HOME=/opt/loopforge/conversation-cli bash >&2"
installer = conversationScriptInstaller(cursorInstallerURL)
case AgentCLIAntigravity:
installer = "curl -fsSL https://antigravity.google/cli/install.sh | HOME=/opt/loopforge/conversation-cli bash >&2"
installer = conversationScriptInstaller(agyInstallerURL)
default:
return "", fmt.Errorf("不支持的会话CLI %s", provider)
}
Expand All @@ -252,6 +274,21 @@ fi
"python3 -c 'import json,urllib.request'\ncommand -v " + shellSingleQuote(binary) + "\n", nil
}

// Download the complete HTTPS installer before executing it. Retry the transfer
// once because a TLS connection failure can be transient.
func conversationScriptInstaller(url string) string {
return "installer_url=" + shellSingleQuote(url) + "\n" + `installer_file=$(mktemp)
trap 'rm -f "$installer_file"' EXIT
download_installer() {
curl -fsSL --proto '=https' --tlsv1.2 --connect-timeout 10 --max-time 45 -o "$installer_file" "$installer_url"
}
if ! download_installer; then
sleep 1
download_installer
fi
HOME=/opt/loopforge/conversation-cli bash "$installer_file" >&2`
}

// Node-based CLIs call getpwuid even when HOME is already set. Numeric
// container users need an NSS identity; do not change an existing image user.
const conversationCLIIdentitySetup = `python3 - "$1" "$2" "$3" <<'LOOPFORGE_CLI_IDENTITY'
Expand Down
107 changes: 107 additions & 0 deletions internal/runtime/conversation_sandbox_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
package runtime

import (
"context"
"os"
"os/exec"
"path/filepath"
"strings"
"testing"

"agentflow/internal/domain"
)

func TestConversationCLISetupUsesSandboxProxy(t *testing.T) {
bin := t.TempDir()
t.Setenv("PATH", bin+string(os.PathListSeparator)+os.Getenv("PATH"))
t.Setenv("AGENTFLOW_RUNTIME_CLI_DIR", "")
argsPath := filepath.Join(t.TempDir(), "setup-args")
t.Setenv("LOOPFORGE_TEST_SETUP_ARGS", argsPath)
docker := writeScript(t, `#!/bin/sh
set -eu
case "$*" in
*"id -u; id -g"*) printf '1000\n1000\n' ;;
*"loopforge-cli-setup"*)
printf '%s\n' "$@" > "$LOOPFORGE_TEST_SETUP_ARGS"
printf '/opt/loopforge/conversation-cli/.local/bin/agy\n' ;;
esac
`)
if err := os.Symlink(docker, filepath.Join(bin, "docker")); err != nil {
t.Fatal(err)
}
sb := &dockerSandbox{name: "workspace", profile: domain.SandboxProfile{Environment: map[string]string{
"HTTPS_PROXY": "http://proxy.example.test:3128",
"no_proxy": "localhost",
"BASH_ENV": "/workspace/profile.sh",
}}}
if _, err := ensureConversationCLI(context.Background(), sb, AgentCLIAntigravity, "/workspace/home"); err != nil {
t.Fatal(err)
}
args, err := os.ReadFile(argsPath)
if err != nil {
t.Fatal(err)
}
for _, option := range []string{"HTTPS_PROXY=http://proxy.example.test:3128", "no_proxy=localhost"} {
if !strings.Contains(string(args), "\n-e\n"+option+"\n") {
t.Errorf("installer missing proxy option %s", option)
}
}
if strings.Contains(string(args), "BASH_ENV=") {
t.Error("installer inherited unrelated workspace shell configuration")
}
}

func TestConversationScriptInstallerRetriesDownload(t *testing.T) {
for _, tc := range []struct {
name string
fail string
}{
{name: "recovers after TLS error", fail: "once"},
{name: "returns persistent TLS error", fail: "always"},
} {
t.Run(tc.name, func(t *testing.T) {
bin := t.TempDir()
t.Setenv("PATH", bin+string(os.PathListSeparator)+os.Getenv("PATH"))
t.Setenv("LOOPFORGE_TEST_DOWNLOAD_MARKER", filepath.Join(t.TempDir(), "first-attempt"))
t.Setenv("LOOPFORGE_TEST_DOWNLOAD_FAILURE", tc.fail)
curl := writeScript(t, `#!/bin/sh
set -eu
while [ "$#" -gt 0 ]; do
case "$1" in -o) output=$2; shift ;; esac
shift
done
echo "download attempted" >&2
if [ -e "$LOOPFORGE_TEST_DOWNLOAD_MARKER" ] && [ "$LOOPFORGE_TEST_DOWNLOAD_FAILURE" = once ]; then
printf '%s' complete > "$output"
exit 0
fi
touch "$LOOPFORGE_TEST_DOWNLOAD_MARKER"
printf '%s' incomplete > "$output"
echo "curl: (35) SSL routines::wrong version number" >&2
exit 35
`)
bash := writeScript(t, `#!/bin/sh
echo "installer invoked"
test "$(cat "$1")" = complete
`)
for name, script := range map[string]string{"curl": curl, "bash": bash} {
if err := os.Symlink(script, filepath.Join(bin, name)); err != nil {
t.Fatal(err)
}
}

output, err := exec.Command("sh", "-ec", conversationScriptInstaller(agyInstallerURL)).CombinedOutput()
if strings.Count(string(output), "download attempted") != 2 {
t.Fatalf("installer download did not retry once: %s", output)
}
ran := strings.Count(string(output), "installer invoked")
if tc.fail == "once" {
if err != nil || ran != 1 {
t.Fatalf("verified download did not install: %v\n%s", err, output)
}
} else if stop, ok := err.(*exec.ExitError); !ok || stop.ExitCode() != 35 || ran != 0 {
t.Fatalf("failed transfer ran the installer or lost curl's exit code: %v\n%s", err, output)
}
})
}
}
Loading
Loading