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
85 changes: 71 additions & 14 deletions deploy/bind-cli.sh
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@
# --uninstall 卸载:通知平台注销机器、停止服务、删除全部文件和配置
#
# 默认直接从平台下载对应 OS/架构的二进制(由服务端 /runners/agentflow-runner 分发)。
# 脚本安装 agentflow-runner 和跨沙箱 Gate MCP helper、写配置并启动
# 脚本安装 agentflow-runner 和跨沙箱 Git/MCP、Gate MCP helper、写配置并启动
# daemon。Runner 仅向平台发起出站 HTTPS,不开放任何入站端口。

set -euo pipefail
Expand Down Expand Up @@ -343,6 +343,7 @@ RUNNER_HOME="${HOME}/.agentflow-runner"
ENV_FILE="${RUNNER_HOME}/env"
STATE_FILE="${RUNNER_HOME}/state.json"
BINARY="${BIN_DIR}/agentflow-runner"
DOCKER_RUNNER_BINARY="${BIN_DIR}/agentflow-runner-linux-${ARCH}"

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] 安装器需要把 helper 写到工作区实际读取的路径。 我在安装和前台启动时都设置了 AGENTFLOW_RUNNER_BINARY=<root>/bundle/{os}/{arch}/agentflow-runner。安装成功后,文件位于 --bin-dir 下,PrepareMCPCall 却在 bundle/linux/arm64/agentflow-runner 报 no such file or directory。全新安装中这个父目录尚不存在,启动修复也在 os.CreateTemp 处失败。请让安装和修复都按运行时规则展开模板,并在目标目录中暂存、发布文件。可以用尚不存在的架构子目录覆盖这个回归。

GATE_BINARY_PATTERN="${BIN_DIR}/agentflow-gate-mcp-{os}-{arch}"
PLIST="${HOME}/Library/LaunchAgents/com.agentflow.runner.plist"
UNIT="${HOME}/.config/systemd/user/agentflow-runner.service"
Expand Down Expand Up @@ -421,6 +422,9 @@ if [[ "$UNINSTALL" == "1" ]]; then
info "已清理 runner Docker 沙箱和临时镜像"
fi
rm -f "$BINARY"
if [[ "$OS" == "darwin" ]]; then
rm -f "$DOCKER_RUNNER_BINARY"
fi
rm -f "${BIN_DIR}"/agentflow-gate-mcp-darwin-amd64 \
"${BIN_DIR}"/agentflow-gate-mcp-darwin-arm64 \
"${BIN_DIR}"/agentflow-gate-mcp-linux-amd64 \
Expand Down Expand Up @@ -537,21 +541,42 @@ case "$(printf '%s' "${AGENTFLOW_BROWSER:-}" | tr '[:upper:]' '[:lower:]')" in
esac

# ---------- 1. 安装二进制 ----------
download_runner_binary() {
local target_os="$1" url
if [[ -n "$DOWNLOAD_URL" && ( "$target_os" == "$OS" || "$DOWNLOAD_URL" == *"{os}"* ) ]]; then
url="${DOWNLOAD_URL//\{os\}/$target_os}"
url="${url//\{arch\}/$ARCH}"
else
url="${SERVER}/runners/agentflow-runner?os=${target_os}&arch=${ARCH}"

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] --from 安装时,Linux helper 的架构需要匹配实际使用的 macOS Runner。 我在 Apple Silicon 的原生 arm64 shell 里用 --from 安装了本提交编译的 Darwin/amd64 Runner。脚本按 uname -m 只下载并安装了 agentflow-runner-linux-arm64。通过 Rosetta 运行的 amd64 进程调用 PrepareMCPCall 时会按 runtime.GOARCH 查找 agentflow-runner-linux-amd64,实测直接报文件不存在。--from 还会关闭自动更新。这条路径需要根据所选宿主二进制确定 helper 的下载架构、校验架构和文件名,或在安装时明确拦下不支持的组合。

fi
info "从 ${url} 下载 agentflow-runner(${target_os}/${ARCH})..."
curl -fsSL "$url" -o "$TEMP_BINARY" && [[ -s "$TEMP_BINARY" ]]
}

build_runner_binary() {
local target_os="$1" source="$2"
info "从源码 ${source} 构建 agentflow-runner(${target_os}/${ARCH})..."
(cd "$source" && CGO_ENABLED=0 GOOS="$target_os" GOARCH="$ARCH" go build -o "$TEMP_BINARY" ./cmd/agentflow-runner)
}

publish_runner_binary() {
[[ -s "$TEMP_BINARY" ]] || fail "下载或构建的 runner 二进制为空"
chmod +x "$TEMP_BINARY"
mv -f "$TEMP_BINARY" "$1"
TEMP_BINARY=""
}

install_binary() {
mkdir -p "$BIN_DIR"
TEMP_BINARY=$(mktemp "${BIN_DIR}/.agentflow-runner.XXXXXX")
if [[ -n "$LOCAL_BINARY" ]]; then
[[ -f "$LOCAL_BINARY" ]] || fail "本地二进制不存在: $LOCAL_BINARY"
cp "$LOCAL_BINARY" "$TEMP_BINARY"
elif [[ -n "$DOWNLOAD_URL" ]]; then
URL="${DOWNLOAD_URL//\{os\}/$OS}"
URL="${URL//\{arch\}/$ARCH}"
info "从 ${URL} 下载二进制..."
curl -fsSL "$URL" -o "$TEMP_BINARY"
download_runner_binary "$OS"
else
# 默认:平台直接分发对应 OS/架构的二进制,无需本机 Go 工具链。
info "从 ${SERVER} 下载 agentflow-runner(${OS}/${ARCH})..."
if curl -fsSL "${SERVER}/runners/agentflow-runner?os=${OS}&arch=${ARCH}" -o "$TEMP_BINARY"; then
if download_runner_binary "$OS"; then
:
else
# 平台未配置分发:回退到本地源码构建(--source 或当前目录为源码 checkout)。
Expand All @@ -564,15 +589,47 @@ install_binary() {
3) 本命令追加 --from <已编译的 agentflow-runner 二进制路径>"
fi
command -v go >/dev/null 2>&1 || fail "本机未安装 Go,无法从源码构建;请使用 --from 提供二进制"
info "从源码 ${SRC} 构建(${OS}/${ARCH})..."
(cd "$SRC" && CGO_ENABLED=0 GOOS="$OS" GOARCH="$ARCH" go build -o "$TEMP_BINARY" ./cmd/agentflow-runner) \
build_runner_binary "$OS" "$SRC" \
|| fail "源码构建失败;请检查 Go 版本(需 1.22+)或改用 --from"
fi
fi
[[ -s "$TEMP_BINARY" ]] || fail "下载或构建的 runner 二进制为空"
chmod +x "$TEMP_BINARY"
mv -f "$TEMP_BINARY" "$BINARY"
publish_runner_binary "$BINARY"
}

is_linux_runner_binary() {
local header machine
case "$ARCH" in
amd64) machine="3e00" ;;
arm64) machine="b700" ;;
esac
# Read the ELF64 little-endian header. e_type and e_machine start at bytes 16 and 18.
header="$(LC_ALL=C od -An -v -t x1 -N 64 "$1" | tr -d '[:space:]')" || return 1
[[ ${#header} -eq 128 && "${header:0:14}" == "7f454c46020101" &&
( "${header:14:2}" == "00" || "${header:14:2}" == "03" ) &&
( "${header:32:4}" == "0200" || "${header:32:4}" == "0300" ) &&
"${header:36:4}" == "$machine" ]]

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] 替换旧 helper 前请校验完整的发布产物。 这里仅检查前 64 字节。我先安装了可工作的 Linux Runner,再让发布端以 HTTP 200 返回同一 ELF 的前 64 字节,Content-Length 也为 64。--upgrade 退出码为 0,原来的 16,422,325 字节文件被覆盖。同一个 Alpine 容器执行 mcp list,升级前成功,升级后报 exec format error。建议在 mv 前校验发布清单中的完整摘要,或验证 ELF 的可加载段及其文件范围,并用这个截断场景断言原 helper 仍可运行。

}

install_docker_runner_binary() {
local source="${SOURCE_DIR:-$PWD}"
# A custom host runner may have a matching helper managed by its installer.
# A per-OS download URL can replace the helper when it is the selected source.
if [[ -x "$DOCKER_RUNNER_BINARY" && -f "$DOCKER_RUNNER_BINARY" &&

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] 保留自定义 helper 时也应识别不兼容的文件。 我把一个有执行位的 Darwin Runner 放在 Linux helper 路径,再执行 --upgrade --from。即使发布端提供了正确的 Linux 产物,安装仍以 0 退出,Linux 下载请求数为 0,原路径留下的仍是 Mach-O。自定义安装默认关闭自动更新,Docker 工作区会持续启动失败。建议只把可在目标平台运行的文件视为已就绪;如果自定义文件不能覆盖,至少应明确报错并指出需要替换的路径。

( -n "$LOCAL_BINARY" ||
( "$DOWNLOAD_URL" != *"{os}"* && ( -n "$DOWNLOAD_URL" || -n "$SOURCE_DIR" ) ) ) ]]; then
info "保留自定义 Runner 的 Linux Git/MCP helper:${DOCKER_RUNNER_BINARY}"
return
fi
TEMP_BINARY=$(mktemp "${BIN_DIR}/.agentflow-runner.XXXXXX")
if { download_runner_binary linux && is_linux_runner_binary "$TEMP_BINARY"; } ||
{ [[ -d "$source/cmd/agentflow-runner" ]] && command -v go >/dev/null 2>&1 &&
build_runner_binary linux "$source" && is_linux_runner_binary "$TEMP_BINARY"; }; then
publish_runner_binary "$DOCKER_RUNNER_BINARY"
return
fi
rm -f "$TEMP_BINARY"
TEMP_BINARY=""
warn "无法获取有效的 Linux/${ARCH} Git/MCP helper,Docker 工作区需要该文件:${DOCKER_RUNNER_BINARY}"
}

TEMP_BINARY=""
Expand All @@ -597,11 +654,11 @@ install_gate_binary() {
chmod +x "$target"
}

# Host sandbox uses the native helper. Docker always uses Linux; on a macOS
# runner both artifacts are therefore required.
# Docker on macOS needs Linux versions of both the Gate MCP and Git/MCP helpers.
install_gate_binary "$OS" "$ARCH"
if [[ "$OS" != "linux" ]]; then
install_gate_binary linux "$ARCH"
install_docker_runner_binary
fi

if [[ "$UPGRADE" == "1" ]]; then
Expand Down
170 changes: 170 additions & 0 deletions deploy/bind_cli_docker_runner_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,170 @@
package deploy

import (
"debug/elf"
"encoding/binary"
"fmt"
"net/http"
"net/http/httptest"
"os"
"os/exec"
"path/filepath"
"testing"
)

func TestBindCLIInstallsDockerRunnerHelper(t *testing.T) {
curl, err := exec.LookPath("curl")
if err != nil {
t.Skip("curl is required for the runner installer")
}
for _, tc := range []struct {
name, hostOS, arch, unameArch string
upgrade bool
helperArtifact, source string
preserveHelper bool
}{
{name: "macOS_install", hostOS: "darwin", arch: "arm64", unameArch: "arm64"},
{name: "macOS_upgrade", hostOS: "darwin", arch: "amd64", unameArch: "x86_64", upgrade: true},
{name: "Linux_install", hostOS: "linux", arch: "arm64", unameArch: "aarch64"},
{name: "macOS_preserves_helper_on_failed_download", hostOS: "darwin", arch: "arm64", unameArch: "arm64", helperArtifact: "unavailable", preserveHelper: true},
{name: "macOS_preserves_helper_when_server_serves_macOS_binary_for_Linux", hostOS: "darwin", arch: "arm64", unameArch: "arm64", upgrade: true, helperArtifact: "mach-o", preserveHelper: true},
{name: "macOS_preserves_helper_when_server_serves_wrong_architecture", hostOS: "darwin", arch: "amd64", unameArch: "x86_64", upgrade: true, helperArtifact: "wrong-arch", preserveHelper: true},
{name: "macOS_preserves_helper_with_local_runner", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "from", preserveHelper: true},
{name: "macOS_preserves_helper_with_host_only_URL", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "host-url", preserveHelper: true},
{name: "macOS_updates_helper_with_explicit_Linux_URL", hostOS: "darwin", arch: "arm64", unameArch: "arm64", source: "template"},
} {
t.Run(tc.name, func(t *testing.T) {
fixtureHome := t.TempDir()
bin := filepath.Join(fixtureHome, "bin")
if err := os.Mkdir(bin, 0o755); err != nil {
t.Fatal(err)
}
uname := fmt.Sprintf("#!/bin/sh\ncase \"$1\" in -s) echo %s ;; -m) echo %s ;; esac\n", tc.hostOS, tc.unameArch)
if err := os.WriteFile(filepath.Join(bin, "uname"), []byte(uname), 0o755); err != nil {
t.Fatal(err)
}
linuxRunner := bindFixtureLinuxRunner(tc.arch, "new helper")
oldHelper := bindFixtureLinuxRunner(tc.arch, "old helper")
hostRunner := linuxRunner
if tc.hostOS == "darwin" {
hostRunner = "\xcf\xfa\xed\xfe" + tc.arch + " macOS runner"
}
if tc.source == "from" {
hostRunner = "custom " + hostRunner
}
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
targetOS, arch := req.URL.Query().Get("os"), req.URL.Query().Get("arch")
if arch != tc.arch || (targetOS != tc.hostOS && targetOS != "linux") {
http.NotFound(w, req)
return
}
switch req.URL.Path {
case "/runners/agentflow-runner":
if targetOS == tc.hostOS {
fmt.Fprint(w, hostRunner)
return
}
switch tc.helperArtifact {
case "unavailable":
http.NotFound(w, req)
case "mach-o":
fmt.Fprint(w, hostRunner)
case "wrong-arch":
fmt.Fprint(w, bindFixtureLinuxRunner("arm64", "new helper"))
default:
fmt.Fprint(w, linuxRunner)
}
case "/runners/agentflow-gate-mcp":
fmt.Fprintf(w, "gate %s/%s", targetOS, arch)
default:
http.NotFound(w, req)
}
}))
defer server.Close()
args := []string{"bind-cli.sh", "--bin-dir", bin, "--no-start"}
helper := filepath.Join(bin, "agentflow-runner-linux-"+tc.arch)
statePath := filepath.Join(fixtureHome, ".agentflow-runner", "state.json")
const state = `{"runnerId":"fixture"}`
if tc.upgrade {
if err := os.Mkdir(filepath.Dir(statePath), 0o700); err != nil {
t.Fatal(err)
}
for path, data := range map[string]string{
statePath: state,
filepath.Join(filepath.Dir(statePath), "env"): "AGENTFLOW_SERVER_URL=" + server.URL + "\n",
filepath.Join(bin, "agentflow-runner"): "old host runner",
} {
if err := os.WriteFile(path, []byte(data), 0o700); err != nil {
t.Fatal(err)
}
}
args = append(args, "--upgrade")
} else {
args = append(args, "--server", server.URL, "--token", "fixture")
}
switch tc.source {
case "from":
custom := filepath.Join(fixtureHome, "custom-runner")
if err := os.WriteFile(custom, []byte(hostRunner), 0o755); err != nil {
t.Fatal(err)
}
args = append(args, "--from", custom)
case "host-url":
args = append(args, "--download-url", server.URL+"/runners/agentflow-runner?os=darwin&arch={arch}")
case "template":
args = append(args, "--download-url", server.URL+"/runners/agentflow-runner?os={os}&arch={arch}")
}
if tc.upgrade || tc.source != "" || tc.preserveHelper {
if err := os.WriteFile(helper, []byte(oldHelper), 0o755); err != nil {
t.Fatal(err)
}
}
cmd := exec.Command("/bin/bash", args...)
cmd.Env = []string{"HOME=" + fixtureHome, "PATH=" + bin + ":" + filepath.Dir(curl) + ":/usr/bin:/bin", "AGENTFLOW_BROWSER=off"}
if out, err := cmd.CombinedOutput(); err != nil {
t.Fatalf("install: %v\n%s", err, out)
}
assertArtifact := func(path, want string) {
t.Helper()
got, err := os.ReadFile(path)
if err != nil || string(got) != want {
t.Fatalf("%s = %q, %v; want %q", filepath.Base(path), got, err, want)
}
if info, err := os.Stat(path); err != nil || info.Mode().Perm()&0o100 == 0 {
t.Fatalf("%s is not executable: %v", path, err)
}
}
assertArtifact(filepath.Join(bin, "agentflow-runner"), hostRunner)
switch {
case tc.hostOS == "linux":
if _, err := os.Stat(helper); !os.IsNotExist(err) {
t.Fatalf("Linux install wrote a duplicate runner: %v", err)
}
case tc.preserveHelper:
assertArtifact(helper, oldHelper)
default:
assertArtifact(helper, linuxRunner)
assertArtifact(filepath.Join(bin, "agentflow-gate-mcp-linux-"+tc.arch), "gate linux/"+tc.arch)
}
if tc.upgrade {
if got, err := os.ReadFile(statePath); err != nil || string(got) != state {
t.Fatalf("upgrade changed runner state: %q, %v", got, err)
}
}
})
}
}

func bindFixtureLinuxRunner(arch, payload string) string {
header := make([]byte, 64)
copy(header, "\x7fELF\x02\x01\x01\x00")
machine := elf.EM_X86_64
if arch == "arm64" {
machine = elf.EM_AARCH64
}
binary.LittleEndian.PutUint16(header[16:], uint16(elf.ET_EXEC))
binary.LittleEndian.PutUint16(header[18:], uint16(machine))
binary.LittleEndian.PutUint32(header[20:], uint32(elf.EV_CURRENT))
binary.LittleEndian.PutUint16(header[52:], uint16(len(header)))
return string(header) + payload
}
4 changes: 4 additions & 0 deletions docs/deployment.md
Original file line number Diff line number Diff line change
Expand Up @@ -133,6 +133,10 @@ The upstream process roles remain `-role api`, `-role worker` and `-role all`. A

Personal runners are connected from the execution-machine page with a short-lived binding code. The installer is served at `/runners/install.sh`. `AGENTFLOW_RUNNER_BINARY` can point to binaries with `{os}` and `{arch}` substitutions. Container images bundle Linux/macOS amd64/arm64 runner and gate binaries. Native source installations can build on demand with Go.

The macOS installer places the matching Linux runner next to the macOS executable. Docker workspaces use it for Git credentials and MCP calls. The installer and updater verify the helper's executable format and CPU architecture before replacing it. Custom host installs keep an existing helper. A download URL with an `{os}` placeholder can supply a replacement when used as the runner's download source.

When platform updates are enabled, macOS runners synchronize the helper in the background at startup and retry if it is missing or incompatible. The runner can report online and accept work during this check. A Docker workspace that needs a missing helper waits for the initial download attempt.

A platform administrator can share one CodeBuddy API Key under **Platform administration → Shared CodeBuddy Key** (平台共享 CodeBuddy Key): pick the network environment that issued it and the models members may use (the first is the default). Members without a key of their own then chat and run SOPs on it, limited to those models; a role configured with another model runs on the default and the run says so. Members with their own key keep using it with any model. Scheduled tasks, clarification, reports, bots and run evaluation still need the runner's own key. A scheduled task uses the key for its selected CLI and does not borrow the shared CodeBuddy key. The key is stored in the database like personal keys and is never shown again after saving. `AGENTFLOW_ASSISTANT_SPONSOR_LOGIN`, which lent one account's key limited to `deepseek-v4.1-flash`, still applies while no shared key is configured.

Configure provider credentials in the platform UI, not the host's global CLI configuration. Credentials are bound to the responsible actor by the upstream runtime. The home composer and SOP roles each choose a built-in CLI independently. Select the executor beside the home model selector; its API key (and optional Codex/Claude base URL) comes from your personal settings. Changing the executor preserves the draft; saved conversations record the executor used. Main Bot writes still pass through the platform tool gateway and its approval checks. Requirement clarification and notifications continue to use CodeBuddy. A scheduled assistant task can select any supported CLI and runs as an ordinary chat turn; Codex and Claude Code still need that account's own credential. Live model tests are opt-in; set `AGENTFLOW_LIVE_TESTS=1` only for the acceptance suites that need to load local credentials.
Expand Down
12 changes: 12 additions & 0 deletions internal/runner/daemon.go
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,7 @@ type Daemon struct {
updateMu sync.RWMutex
updateReady atomic.Bool
updateDownloadMu sync.Mutex
dockerHelperSyncDone chan struct{} // closed after the initial macOS helper sync
cancelClaimLoop context.CancelFunc
heartbeatWake chan struct{}
maintenance runnerMaintenanceState
Expand Down Expand Up @@ -157,6 +158,9 @@ func (d *Daemon) Run(ctx context.Context) error {
claimCtx, cancelClaim := context.WithCancel(ctx)
defer cancelClaim()
d.cancelClaimLoop = cancelClaim
if goruntime.GOOS == "darwin" && !d.cfg.DisableAutoUpdate {
d.dockerHelperSyncDone = make(chan struct{})
}
go d.rescanLoop(ctx)
heartbeatDone := make(chan struct{})
go func() { defer close(heartbeatDone); d.heartbeatLoop(ctx) }()
Expand All @@ -172,6 +176,9 @@ func (d *Daemon) Run(ctx context.Context) error {
<-controlDone
d.maintenance.jobs.Wait()
<-heartbeatDone
if d.dockerHelperSyncDone != nil {
<-d.dockerHelperSyncDone
}
closeCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
d.closeAllRunSandboxes(closeCtx)
cancel()
Expand Down Expand Up @@ -372,6 +379,10 @@ func (d *Daemon) availableProviders() []string {
}

func (d *Daemon) rescanLoop(ctx context.Context) {
if d.dockerHelperSyncDone != nil {
d.refreshDockerRunnerHelper(ctx, false)
close(d.dockerHelperSyncDone)
}
ticker := time.NewTicker(5 * time.Minute)
defer ticker.Stop()
for {
Expand All @@ -380,6 +391,7 @@ func (d *Daemon) rescanLoop(ctx context.Context) {
return
case <-ticker.C:
d.refreshRuntimes(ctx)
d.refreshDockerRunnerHelper(ctx, true)
d.reapIdleRunSandboxes(ctx, runSandboxIdleTTL)
}
}
Expand Down
5 changes: 5 additions & 0 deletions internal/runner/run_sandbox.go
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,11 @@ func (d *Daemon) acquireTaskSandbox(ctx context.Context, task domain.RunnerTask)
if task.Sandbox == nil {
return nil, nil, fmt.Errorf("frozen run sandbox definition is required")
}
if strings.TrimSpace(task.Sandbox.Profile.Driver) == domain.SandboxDriverDocker {
if err := d.waitForDockerRunnerHelper(ctx); err != nil {
return nil, nil, err
}
}
requirements, resources := taskSandboxSpec(task)
key, id, shared := runSandboxKey(task, requirements, resources)
if !shared || d.cfg.DisableRunSandboxReuse {
Expand Down
Loading
Loading