A3S WebView

a3s-webview is a tiny native WebView helper for the a3s code terminal UI. The TUI cannot embed a browser inside its terminal grid, so it can spawn this helper when a runtime returns a partial viewUrl that is intended to open as a sized popup instead of a full browser tab.

It opens one native window, loads one http:// or https:// URL, and exits when the window is closed.

The current crate version is a3s-webview 0.1.3. Its repository metadata points to A3S-Lab/WebView.

Capability Map

Area	Current capability
Window helper	Opens one focused native window at a requested logical size and title.
Agent Island	Reads the private system-agent snapshot and owns the per-user native island singleton.
URL policy	Requires `--url`, accepts only `http://` and `https://`, and exits with usage errors for unsupported schemes or unknown arguments.
Size guardrails	Width is clamped to `240..4000`; height is clamped to `180..3000`. Defaults are `900 x 680`.
Auth seeding	Reads an access token from an environment variable before navigation and seeds browser storage without putting the token in argv.
Refresh token	Also reads `A3S_OS_REFRESH_TOKEN` when present and stores it with the session.
User bootstrap	Uses same-origin `GET /api/v1/users/me` to seed the user object before the embedded app boots.
Headers	Supports repeated `--header 'Name: Value'` arguments for host-provided request metadata.
Navigation	macOS uses native AppKit titlebar buttons; Linux and Windows inject a small back/forward/reload toolbar.
Platform backends	macOS WKWebView, Linux WebKitGTK, and Windows WebView2 through `wry` and `tao`.

Start Here

Usage covers command-line arguments, URL validation, headers, size clamp behavior, and install paths.
Auth Bootstrap explains storage seeding, same-origin user bootstrap, and why tokens stay out of argv.
Platforms And Boundaries covers WKWebView, WebKitGTK, WebView2, navigation controls, fallback ownership, and what this helper does not try to be.

Usage

a3s-webview --url <http(s)://URL> [--width N] [--height N] [--title T]
            [--header 'Name: Value']... [--token-env NAME] [--no-auth]

a3s-webview --agent-island --snapshot <absolute-path>
            --lock-file <absolute-path>

Flag	Behavior
`--url`	Required. Must start with `http://` or `https://`.
`--width` / `--height`	Optional logical pixel size, clamped to safe bounds.
`--title`	Optional native window title. Hosts should pass a product-appropriate title.
`--header`	Adds one request header; repeatable. Header syntax must be `Name: Value`.
`--token-env`	Environment variable that holds the access token. Default: `A3S_OS_TOKEN`.
`--no-auth`	Disables browser-storage auth seeding.

Use environment variables for session credentials. --header values are command line arguments, so do not pass sensitive bearer tokens through that flag unless the host process model already treats argv as protected.

Auth Bootstrap

Many embedded runtime pages restore login state from browser storage rather than cookies. a3s-webview handles that case before the page's own scripts run:

Read the access token from --token-env or A3S_OS_TOKEN.
Store it as both access_token and auth_token.
If A3S_OS_REFRESH_TOKEN is set, store refresh_token.
Resolve the current user with same-origin GET /api/v1/users/me.
Store the returned user object as auth_user.

If the access token is missing or --no-auth is set, the helper opens the URL without auth seeding.

Install

a3s install webview
brew install a3s-lab/tap/a3s-webview
cargo install --git https://github.com/A3S-Lab/WebView

a3s code reuses a healthy helper or installs its verified platform release before terminal takeover when networking and automatic setup are allowed. --offline, A3S_OFFLINE=1, and A3S_NO_AUTO_INSTALL=1 disable that first-use mutation. On macOS, the Homebrew a3s formula can install a3s-webview alongside the umbrella CLI.

Platform Notes

Platform	Backend	Notes
macOS	WKWebView	Uses the system framework and native titlebar navigation controls.
Linux	WebKitGTK	Requires WebKitGTK development/runtime packages when building from source.
Windows	WebView2	Uses the WebView2 runtime that ships with modern Windows.

If first-use setup fails, a3s code continues and can fall back to opening normal links in the system browser. That fallback is owned by the TUI host, not by the helper process itself.

Boundaries

This is not the documentation site UI.
This is not the agent runtime.
It is for partial, trusted runtime popup views that accompany terminal workflows.
Plain inspectable links should still open in the user's normal browser.

A3S WebView

On this page