Version: 0.1.0 prototype. Read the capability table before selecting an engine.
Go 1.24+ is required by the secure file-root implementation. Dependencies are vendored. The SDK has no Node.js, Python, Playwright server or ChromeDriver runtime dependency.
mkdir -p bin test-results
CGO_ENABLED=0 go build -buildvcs=false -mod=vendor -o bin/cfbrowser ./cmd/cfbrowser
CGO_ENABLED=0 go build -buildvcs=false -mod=vendor -o bin/cfbrowser-worker ./cmd/cfbrowser-worker
go test -mod=vendor ./...
On PowerShell, set $env:CGO_ENABLED="0", then use go build -buildvcs=false -mod=vendor -o bin/cfbrowser.exe ./cmd/cfbrowser. Build ./cmd/cfbrowser-worker as bin/cfbrowser-worker.exe too. Windows uses the installed Evergreen WebView2 Runtime; macOS uses system WKWebView (11+). See native build and runtime tests.
For CDP, install Chrome/Chromium/Edge separately or point to an already installed executable. Chrome Headless Shell is also usable for headless workloads. Browser downloads are never automatic.
For native Linux, install GTK3 and WebKitGTK 4.1 runtime libraries. For example, on a compatible Ubuntu system: sudo apt install libgtk-3-0t64 libwebkit2gtk-4.1-0. Package names and available WebKitGTK versions vary by distribution. Rocky 9 has not been runtime-tested. Do not symlink a 4.0 or 6.0 ABI to 4.1.
The native backend needs an X11/Wayland graphical environment. A CI machine may use Xvfb. The SDK's Headed=false means a hidden native top-level window, not displayless GTK.
All flags precede the command.
./bin/cfbrowser --browser /path/to/chrome doctor
./bin/cfbrowser --browser /path/to/chrome demo
./bin/cfbrowser --browser /path/to/chrome --export-dir /existing/folder demo
./bin/cfbrowser --engine native --worker ./bin/cfbrowser-worker demo
./bin/cfbrowser --engine native --worker ./bin/cfbrowser-worker --diagnostics demo
./bin/cfbrowser --browser /path/to/chrome serve
doctor reports implemented capabilities and executable discovery. It returns runtimeVerified=false: this command does not launch a browser or prove that GTK can open a display. demo exercises the actual engine against a local fixture.
| Flag | Meaning |
|---|---|
--engine cdp/native |
Explicit engine; no silent fallback |
--browser PATH |
Trusted-host Chromium executable |
--worker PATH |
Trusted-host native worker executable |
--headed |
Show a window from startup; not an interactive handoff system |
--allow-origin ORIGIN |
Authorize an exact private origin, including port; repeatable |
--data-dir DIR |
Base for a private instance directory, removed by Close |
--export-dir DIR |
Demo-only authorized screenshot export root; must already exist |
--no-sandbox |
Explicit isolated-CI exception for Chromium or WebKit; off by default |
--diagnostics |
Forward native engine stderr; it may contain site/runtime details |
The demo grants its own ephemeral HTTP origin, so it does not require a general localhost allowance. An existing export file causes a no-overwrite error.
manager, err := cfbrowser.New(cfbrowser.Config{
Executable: "/path/to/chrome",
MaxSessions: 2,
MaxPages: 3,
MaxResultBytes: 64 * 1024,
MaxDownloadBytes: 100 * 1024 * 1024,
Timeout: 30 * time.Second,
Policy: policy.URLPolicy{
AllowOrigins: []string{"http://127.0.0.1:18900"},
},
}, &cdp.Driver{})
For native Windows/macOS/Linux, pass &native.Driver{WorkerPath: "/path/to/cfbrowser-worker"} instead. native is the import alias for clusterflow.dev/cfbrowser/driver/native. Native driver options may include a trusted Diagnostics io.Writer.
Always handle the returned error before using the manager and defer manager.Close(). Use a stable api.Owner built from the actual host execution scope. Every EnvironmentID, ThreadID and RunID is required. SSHSessionID is optional but participates in equality when supplied. A child Agent must use its own RunID.
One session owns one dedicated browser process or native worker. Pages within it share cookies/storage. Different sessions do not. A new run cannot adopt an old session merely by knowing its ID; lease transfer is not implemented.
DataDir is a temporary-storage base, not a persistent profile directory. Closing a session removes its managed downloads. Export important results before closing. Closing the manager removes its entire private instance directory.
owner := api.Owner{EnvironmentID: "ssh1", ThreadID: "thread1", RunID: "run1", SSHSessionID: "connection1"}
session, err := manager.CreateSession(ctx, owner)
// Check err before using session.
page, err := manager.NewPage(ctx, owner, session.ID)
// Check err before using page.
| Manager method | Purpose |
|---|---|
Capabilities(ctx) |
Engine feature implementation status |
CreateSession(ctx, owner) |
Reserve quota and start a dedicated isolated engine |
Sessions(owner) |
List only this owner's sessions |
NewPage(ctx, owner, sessionID) |
Add a managed page |
Navigate(ctx, owner, sessionID, pageID, url, operation) |
goto/back/forward/reload |
Snapshot(ctx, owner, sessionID, pageID, request) |
Bounded fresh semantic refs |
Act(ctx, owner, sessionID, pageID, request) |
Single validated element action |
Read(ctx, owner, sessionID, pageID, request) |
Bounded text/table extraction |
Wait(ctx, owner, sessionID, pageID, request) |
Cancellable ready/URL/text/textGone wait |
Capture(ctx, owner, sessionID, pageID) |
CDP viewport PNG in managed storage |
Files(ctx, owner, sessionID) |
Import completed CDP downloads and list metadata |
Export(ctx, owner, sessionID, fileID, authorizedRoot, relativePath) |
No-overwrite export confined to an authorized root |
ClosePage(ctx, owner, sessionID, pageID) |
Close one page and reclaim page quota |
CloseSession(owner, sessionID) |
Close the owning engine and clear session storage |
Close() |
Idempotent manager shutdown |
Operations on a page are serialized with a cancellable gate. Operations on different pages may proceed concurrently. Resource quotas count managed pages; arbitrary page-generated popups are outside the prototype page API and are not a complete browser-resource sandbox.
snapshot, err := manager.Snapshot(ctx, owner, sessionID, pageID, api.SnapshotRequest{
Mode: "interactive", MaxBytes: 12 * 1024, MaxElements: 100,
})
Modes are compact and interactive. The result is kind=dom-semantic, not a complete accessibility tree. Refs identify actual element objects in an isolated script world, not page-editable attributes. Password and file-input values are excluded.
result, err := manager.Act(ctx, owner, sessionID, pageID, api.ActionRequest{
SnapshotID: snapshot.SnapshotID,
Ref: "e1",
Action: "fill",
Value: "La2O3",
})
Find the actual ref in the returned elements rather than assuming e1 always means the same field. New snapshots conservatively invalidate all previous refs. DOM replacement, changed element identity/name/link or navigation may also invalidate them.
| Action | CDP | Native (all platforms) |
|---|---|---|
| click | Browser-dispatched mouse input | Synthetic DOM click |
| hover | Browser mouse input | Unsupported |
| fill | Browser keyboard selection and text insertion | Native value setter plus input/change events |
| type | Browser text insertion | Unsupported |
| press | Enter, Tab, Escape, ArrowUp/Down, Backspace | Unsupported |
| select/check/uncheck/scroll | Bounded DOM operation | Bounded DOM operation |
result.InputKind distinguishes browser from synthetic. Even with the CDP backend, select/check/scroll use DOM operations. effect=dispatched only confirms dispatch. If a connection disappears during a possible side effect, BROWSER_ACTION_OUTCOME_UNKNOWN tells the host to observe before deciding whether another action is appropriate. The SDK never retries actions automatically.
text, err := manager.Read(ctx, owner, sessionID, pageID, api.ReadRequest{Mode: "text", MaxBytes: 24576})
table, err := manager.Read(ctx, owner, sessionID, pageID, api.ReadRequest{Mode: "table", Ref: tableRef, SnapshotID: snapshotID})
err = manager.Wait(ctx, owner, sessionID, pageID, api.WaitRequest{Kind: "text", Value: "Results", TimeoutMS: 5000})
Wait kinds: ready, url substring, text, textGone. No networkidle assumption is made. Waiting does not call a model. The earliest caller deadline, Manager Timeout and optional wait timeout wins.
Snapshot/read budgets refer to final serialized JSON bytes, including escaping. Element scans, label extraction and text scans are bounded. A snapshot scans at most 4,000 DOM elements, returns at most 150 refs and clips names/values. Text/table extraction is intentionally finite; truncated=true must be respected. No continuation or diff protocol exists in v0.1.
CDP downloads use the actual browser network state, preserving cookies, Referer, POST response semantics and blob handling. Poll Files with a cancellable host wait until the expected file is available. The method lists only completed imports; an unfinished or canceled download is not reported as a completed file.
files, err := manager.Files(ctx, owner, sessionID)
// Check err and select an expected file before exporting it.
info, err := manager.Export(ctx, owner, sessionID, files[0].ID, authorizedRoot, "paper.cif")
The host must resolve authorizedRoot from its real local-file grants. It is not a model argument. os.OpenRoot confines the destination and rejects escapes through symlinks. Parent directories must exist. Existing files are never overwritten. File metadata contains an opaque ID, sanitized name, MIME, size and SHA-256, never an absolute path.
Defaults: 100 MiB per download, 64 managed files per session, 4 MiB per screenshot. Chromium's progress-based cancellation is not a hard disk quota against a hostile server; use OS storage limits where required. Native downloads/screenshots and file uploads are not implemented.
Use agenttools.Catalog() for eight descriptors and agenttools.Service{Manager: manager}.Call(ctx, owner, name, arguments) for execution. Apply the host's approval policy before Call. The library does not replace ClusterFlow's permission system.
{"operation":"create"}
This is the model argument for cf_browser_session. Its response includes session and an initial page. Then use cf_browser_navigate, cf_browser_snapshot, cf_browser_act, cf_browser_read, cf_browser_wait, cf_browser_capture and cf_browser_files.
The CLI serve command uses a 4-byte big-endian length plus UTF-8 JSON; maximum frame size is 512 KiB. It supports capabilities, tools.list, tools.call and request.cancel. Owner identity appears only in the trusted host envelope:
{"version":1,"id":1,"method":"tools.call","params":{"owner":{"environmentId":"ssh1","threadId":"t1","runId":"r1"},"name":"cf_browser_session","arguments":{"operation":"list"}}}
deadline is an optional Unix-millisecond timestamp. Responses echo id, carry protocol version=1 and contain either result or a stable error. Up to 32 calls may be pending. The native worker has its own trusted internal protocol; do not expose its Evaluate method as a model tool.
Run python3 scripts/pipe_demo.py ./bin/cfbrowser serve to test framing without starting a browser. Python is only a demonstration client, not an SDK dependency. EOF cancels handlers and closes the manager. Native worker stderr is separate from protocol stdout.
BROWSER_ENGINE_NOT_FOUND: configure a real executable. WebView2 runtime installation alone is not a full Edge browser installation.--diagnostics only while diagnosing locally.--browser msedge.exe selects a full browser for CDP; it is unnecessary for --engine native. Windows native embeds WebView2 through COM; it does not launch full Edge with remote debugging.BROWSER_STALE_REF: take a new snapshot and use its refs.BROWSER_TARGET_NOT_ACTIONABLE: the element is hidden, disabled or obscured; observe/wait before another action.BROWSER_NETWORK_BLOCKED: authorize a specific private origin through host configuration if it belongs to the task.BROWSER_CAPABILITY_UNSUPPORTED.URL validation checks explicit navigation only. It does not constrain every redirect, subresource, Service Worker, WebSocket or DNS re-resolution. This prototype is suitable for a trusted desktop/network test environment, not as a strict multi-tenant web sandbox. A production egress gateway remains part of the longer-term design.