deer-flow/docker/lark-cli-broker/README.md

lark-cli broker image (Pattern B)

This image implements Pattern B (issue #4338): instead of mounting the per-user Lark credential directories into the sandbox (Pattern A still does), a long-running sidecar holds lark-cli + the credentials and serves only the command surface over loopback. The sandbox gets a tiny lark-cli shim on PATH that forwards argv/stdin to the sidecar.

Result: the raw appSecret / OAuth token files never exist in the sandbox filesystem, so a compromised or prompt-injected agent can no longer cat/exfiltrate them — while any authorized lark-cli subcommand still runs.

Two modes, one image

Dispatched by the first CLI argument:

• install-shim <dest> — init container: writes the launcher + Python shim + .deerflow-lark-cli-runtime.json (kind: "shim") into the shared emptyDir at <dest> (default /mnt/integrations/lark-cli/runtime), then exits 0. The sandbox then finds bin/lark-cli exactly where lark_cli_env_overlay(sandbox_paths=True) points PATH — same layout the Pattern A init image produces.
• serve (default CMD) — sidecar: runs the broker HTTP server on 127.0.0.1:8788 with the real lark-cli and the credential env pointing at the sidecar-only /var/lark/{config,data} mounts.

The executable on PATH (bin/lark-cli) is a /bin/sh launcher that resolves a Python 3 interpreter and execs the shim body (bin/lark-cli-shim.py) beside it (by its baked-in absolute path, since $0 is the bare command name when run off PATH); both are written from the in-process LARK_CLI_BROKER_LAUNCHER_TEMPLATE / LARK_CLI_BROKER_SHIM_SCRIPT (deerflow.integrations.lark_broker), so the image's copies can never drift from the Gateway's. Splitting the sh launcher from the Python body means broker mode does not hard-depend on python3 resolving via a #!/usr/bin/env python3 shebang: if no python3/python is on the sandbox PATH, the launcher exits 127 with an actionable message (set DEERFLOW_LARK_BROKER_PYTHON to a known interpreter path) instead of an opaque ENOEXEC. The stock all-in-one-sandbox image ships Python 3, so the default path needs no configuration.

Build

Build context is the repo root (the broker module lives under backend/):

docker build -t deer-flow/lark-cli-broker:v1.0.65 \
  --build-arg LARK_CLI_VERSION=v1.0.65 \
  -f docker/lark-cli-broker/Dockerfile .

The tag should encode the lark-cli version so it can be bumped independently of the upstream all-in-one-sandbox image.

CI publishes multi-arch (linux/amd64,linux/arm64) images to ghcr.io/<owner>/deer-flow-lark-cli-broker:<lark-cli-version> via .github/workflows/lark-cli-images.yaml (run it with a lark_cli_version input, or push a lark-cli-v* tag). This is decoupled from the DeerFlow v* release because the image tracks the upstream larksuite/cli version.

Wiring it into the provisioner

Broker mode is opt-in and off by default. Enable it by publishing this image and pointing the provisioner at it:

• Set LARK_CLI_BROKER_IMAGE on the provisioner to the published tag. Empty ⇒ broker off (Pattern A / legacy path, no behavior change).
• When set, and the Gateway sends provision_lark_cli_broker on sandbox create, the provisioner adds:
  • a lark-cli-runtime emptyDir shared by an init container and the sandbox;
  • a lark-cli-shim-init init container (install-shim) that stages the shim;
  • a lark-cli-broker sidecar (serve) with the per-user config (RO) / data (RW) credential mounts — into the sidecar only;
  • the sandbox container gets the runtime RO mount + DEERFLOW_LARK_BROKER_URL and no config/data mounts.
• Broker mode supersedes Pattern A when both are configured.
• The provisioner reports it via GET /api/capabilities ({"lark_cli_broker_image": true|false}), which the Gateway surfaces as the Lark integration sandbox-runtime readiness signal in /api/integrations/lark/status (sandbox_runtime_mode: "broker").

Opt-in note: broker mode stays off until LARK_CLI_BROKER_IMAGE is set on the provisioner, so an unpublished or unconfigured image is a no-op (Pattern A / legacy path, no behavior change).

Broker HTTP contract (loopback)

• POST /v1/exec — body {"args": [...], "stdin_b64": "..."}; response {"exit_code", "stdout_b64", "stderr_b64", "truncated"}. args is run with shell=False, so a sandbox-supplied argument can never be shell-injected. The broker injects the credential env itself; the client cannot override it. Unexpected broker-side errors return a 500 {"error": ...} so the shim always gets a structured response rather than an opaque transport failure.
• GET /v1/health — {"ok": true}.

Bound to loopback only. In K8s the sandbox and sidecar share the Pod network namespace, so 127.0.0.1 reaches the sidecar and nothing outside the Pod can.

No file I/O relative to the sandbox cwd

The broker runs lark-cli in the sidecar's working directory and cannot see the sandbox filesystem, so the sandbox's cwd is intentionally not forwarded. lark-cli subcommands that read or write files by a path relative to the sandbox cwd (e.g. uploading a local file) are therefore unsupported in broker mode — this is a command-surface-only bridge, not a filesystem bridge. Absolute paths still refer to the sidecar's filesystem, not the sandbox's.

Optional subcommand denylist (hardening)

The broker removes the credential files from the sandbox, but the full lark-cli command surface stays reachable, so any subcommand that prints/exports tokens could still exfiltrate them. Set DEERFLOW_LARK_BROKER_DENY_SUBCOMMANDS on the sidecar to a comma-separated list of command prefixes the broker should refuse (matched against the leading non-flag tokens), e.g. DEERFLOW_LARK_BROKER_DENY_SUBCOMMANDS="config show, auth token". Denied calls return exit 126 with a subcommand ... is disabled message and never spawn the binary. Empty by default (no behavior change); confirm the deployed lark-cli version's subcommand surface has no trivial secret-dump command before enabling broker mode in production.