Skip to content

docs(deployment): document the Agent browser sidecar image - #1172

Open
linus-liu-web wants to merge 1 commit into
Tencent:mainfrom
linus-liu-web:docs/agent-browser-sidecar
Open

linus-liu-web wants to merge 1 commit into
Tencent:mainfrom
linus-liu-web:docs/agent-browser-sidecar

Conversation

@linus-liu-web

@linus-liu-web linus-liu-web commented Nov 21, 2026 •

Copy link
Copy Markdown

Companion: #1173 fixes the failure reporting and keeps the first sidecar image build alive when the request times out; this PR documents how to prebuild and supply that image.

What changed

The Agent browser needs a separate sidecar image (agentflow-browser-<hash>, about 1 GB) that the platform builds from assets embedded in the platform image on first use. The deployment guide documents the sandbox image and the general Docker/git build limits, but never mentions this sidecar, its prebuild command, or the environment settings that control how it is produced.

Add a paragraph to Docker sandboxes that covers:

  • what the sidecar is, when it is built, and that it is reused while the platform version and assets are unchanged;
  • prebuilding with docker compose exec platform /app/bin/agentflow -browser-image (prints the image name, no-op while the image is present);
  • the build's network dependencies (deb.debian.org for Chromium and fonts, npm registry defaulting to registry.npmmirror.com, overridable with AGENTFLOW_BROWSER_NPM_REGISTRY);
  • supplying a prebuilt image through AGENTFLOW_BROWSER_IMAGE on the platform service;
  • image size and docker rmi cleanup.

Cross-reference the paragraph from Slow networks: clone and image build limits, since the browser build is not governed by those settings.

Related to #1160: the first UI use of the browser waits on this build under the request's own 4-minute limit, so on a slow network the build can be cancelled and reported as Chromium being unavailable. This PR documents how to prebuild and supply the image; it does not change that behavior.

Scope

  • Documentation only
  • Platform core / API / runner
  • Public adapter / deployment
  • Classic
  • Portable
  • Shared behavior contract
  • Installer / CLI

Compatibility

No behavior or schema change.

Validation

  • python3 scripts/check-public.py passes on the patched worktree.
  • Ran the documented command on a v0.4.1-rc.1 Compose install with the sidecar image already present: docker compose exec -T platform /app/bin/agentflow -browser-image printed agentflow-browser-<hash> in about 0.3 s without rebuilding; docker images shows the image at 1.06 GB, matching the documented size.
  • Checked the documented settings against the code: -browser-image in cmd/agentflow/main.go, AGENTFLOW_BROWSER_IMAGE / AGENTFLOW_BROWSER_NPM_REGISTRY in internal/runtime/browser.go, npm registry default in internal/runtime/browser_assets/Dockerfile.
  • Not run: the full Go suite (go test -p=2 ./...); documentation only.

Safety

  • I did not include credentials, internal endpoints, production data, or organization-specific infrastructure.
  • I preserved user files and unrelated changes.
  • I updated generated Classic host bundles when applicable. (n/a — no Classic change)
  • I documented third-party content and licensing changes when applicable. (n/a)

The Agent browser needs a separate agentflow-browser-<hash> image (about 1 GB)
that the platform builds from assets embedded in the platform image on first
use. Nothing on the default installation path prebuilds it and the deployment
guide never mentions it, so operators on slow networks meet a first-use build
with no documented way to prepare for it or to supply a prebuilt image.

Document the sidecar and its reuse rules, the -browser-image prebuild command,
the AGENTFLOW_BROWSER_NPM_REGISTRY and AGENTFLOW_BROWSER_IMAGE settings, image
size and cleanup, and cross-reference it from the slow-network guidance.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant