AgentTab v2 is currently local, prerelease source at 2.0.0-rc.1. It has no public package, signed release artifact, Chrome Web Store installation, or hosted setup page. Chrome Bridge v1.0.1 is still the public stable legacy path.
This guide distinguishes the contributor source path from the future signed RC and stable paths. Do not substitute an old Chrome Bridge script, Python host, TCP port, bearer token, or hand-written native-host manifest for any of them.
- Chrome must be version 127 or later for the current extension manifest.
- AgentTab runs in the existing signed-in Chrome profile. It is task-scoped browser control, not a separate profile, cookie jar, or identity boundary.
- Keep page content untrusted. The built-in 1Password broker is available by default and may fill an origin-matching Login item without exposing its value to the agent. Use Needs your attention notices for passkeys, security keys, CAPTCHA, payment secrets, account recovery, unsupported verification, and any credential result that requests the user. Recognized consequential actions execute directly unless YOLO mode is turned off in the popup for staged Commit review.
- A future installation needs an AgentTab extension and the
dev.agenttab.hostnative host. Standard mode does not require a TCP listener, a bearer token, or a Python process. Credential filling additionally requires theopcommand, 1Password desktop-app integration, and biometric unlock available to the current OS user.
The product boundary and residual Commit risk are described in the runtime ADR and Security.
A checkout is a contributor build path, not a supported consumer installation. From the repository root, the following pathless commands build the source components. They are written for POSIX shells, PowerShell, and cmd.exe when run from the repository root:
bun install --frozen-lockfile
bun run extension:build
bun run workspace:build
cargo build --locked --manifest-path host-rs/Cargo.toml
bun run extension:build creates the unpacked development extension in packages/extension/dist/ from the canonical source in packages/extension/src/. bun run workspace:build builds the TypeScript adapters, installer packages, and site. The Rust command builds the host workspace.
These commands do not create a public release, verify a signed artifact, register a complete consumer installation, or make the extension available through the Chrome Web Store. This repository does not publish a manual source host-registration recipe. The supported consumer path must be the artifact-verifying installer once an RC is available.
When, and only when, an explicitly signed 2.0.0-rc.1 package and immutable RC artifact manifest are made available to approved testers, the intended command is:
npx agenttab@2.0.0-rc.1 install --version 2.0.0-rc.1 --verify-readiness
That is not a command to run today. The package and signing material are not public. The installer rejects latest URLs, verifies the signed manifest, requires the exact vX.Y.Z tag and matching host asset, then records an install receipt. --verify-readiness opens Chrome unless --no-open-browser is supplied, creates a disposable task tab, captures an accessibility snapshot, and closes the tab.
For an approved development artifact, agenttab install --development accepts an explicitly supplied manifest URL, signature URL, and public-key file. Those inputs are supplied by the release workflow, not inferred from a local checkout. See the exact flag behavior in Commands.
After signing, registry, Chrome Web Store, controlled-domain, and platform gates are complete, the stable host installation flow will be:
npx agenttab install
This is a future command, not evidence of a live package. The final stable flow requires the publicly reachable AgentTab extension from the Chrome Web Store and the matching versioned installer artifact. Until those are published, load only a development extension for approved source or RC testing.
The installer deliberately stages the extension but does not silently install or enable a browser extension. Its result identifies the extension directory. For an approved source or RC test:
- Open
chrome://extensionsin Chrome. - Enable Developer mode.
- Choose Load unpacked and select the installer-reported AgentTab extension directory. For a source build, that is
packages/extension/dist/. - Confirm that AgentTab is enabled.
- Open the AgentTab popup and choose Enable AgentTab automation. Chrome requests the optional
scriptingpermission. The requireddebuggerpermission is already present from extension installation; both capabilities are required for Standard browser automation. - Run
agenttab doctor --layer extensionafter the extension is enabled. Useagenttab doctor --layer ipcto check the local host path.
The manifest keeps nativeMessaging, debugger, tabs, tabGroups, storage, and alarms as required permissions because Chrome rejects debugger in optional_permissions. scripting is optional and is requested only from the user-facing popup. Removing it disables automation and detaches active task debugger sessions until it is enabled again.
The frozen native host identity is dev.agenttab.host. The extension build derives its stable development identity and the native-host allowed origins from config/identity.json. Do not edit a generated native-host JSON, substitute an extension ID, or add an origin by hand.
A successful installer registers the same native-host manifest for supported browser locations:
| Platform | Native Messaging registration |
|---|---|
| macOS | Per-user Chrome, Chromium, and Microsoft Edge NativeMessagingHosts directories below ~/Library/Application Support/. |
| Linux | Per-user Google Chrome, Chromium, and Microsoft Edge NativeMessagingHosts directories below ~/.config/. |
| Windows | A manifest below the installer state directory plus current-user HKCU registrations for Chrome, Chromium, and Microsoft Edge. |
The Rust host uses AGENTTAB_STATE_DIR when it is explicitly set. Without it, the host root is ~/.agenttab on Unix and %LOCALAPPDATA%\AgentTab on Windows. The installer has its own --state-dir default of ~/.agenttab; use its receipt rather than assuming that the installer directory is the host state root on Windows. The TypeScript client also uses AGENTTAB_STATE_DIR for private resume-capability storage and for its Unix fallback endpoint.
Normal local adapter traffic uses one of these OS-native endpoints:
| Platform | Endpoint |
|---|---|
| macOS and Linux | $XDG_RUNTIME_DIR/agenttab/agenttab.sock only when that runtime directory belongs to the current user; otherwise $AGENTTAB_STATE_DIR/run/agenttab.sock, defaulting to ~/.agenttab/run/agenttab.sock. |
| Windows | \\.\pipe\agenttab-<current-user-SID>. |
On Unix, AgentTab requires its state and runtime directories to be current-user owned and mode 0700; its socket and host lock are mode 0600. The host authenticates local peers with OS credentials. On Windows, the named-pipe DACL is limited to the current user SID and SYSTEM. AGENTTAB_SOCKET and AGENTTAB_PIPE_NAME are adapter overrides for configured local endpoints, not normal setup switches.
Credential filling is available by default. AgentTab resolves op from the
native host's process PATH, then checks standard installation locations for
the current platform. Owner-only ~/.agenttab/policy.json can disable the
broker or constrain its executable, account, and limits:
{
"one_password": {
"enabled": true,
"max_candidates": 3,
"max_attempts": 3,
"auth_timeout_ms": 45000
}
}The limits must be integers from one through three. auth_timeout_ms must be
between 5000 and 120000. An optional account selects one configured
1Password account without putting a secret in policy. Set executable to the
absolute op path when a GUI-launched browser does not inherit the shell
PATH; relative paths are rejected. Set enabled to false to disable
credential access. Policy changes apply when the native host next starts, so
reload the extension after editing this file.
Install and sign in to 1Password CLI separately, enable its desktop-app integration, and keep the platform's supported biometric or desktop approval available. AgentTab never stores a 1Password session token. If 1Password needs approval, its native 1Password prompt is the only expected human interaction. More than the configured number of origin-matching Login items, unavailable CLI state, or an unsupported verification step returns control to the user instead of trying additional credentials.
AgentTab v2 is side-by-side and recoverable:
- Leave the existing Chrome Bridge extension,
com.automation.bridgenative-host registration, legacy token or policy files, and logs intact. - Install and prove AgentTab first, including an enabled extension and a successful
agenttab doctorcheck. - Only then disable the old unpacked Chrome Bridge extension manually in
chrome://extensions. - Keep v1 repair or recovery work pinned to
v1.0.1until the v2 release is public.
The installer detects the old native-host registration and known legacy state artifacts, reports them, and leaves them untouched. It never silently removes the v1 extension, registration, files, policies, or logs.
The installer stages changed files, creates backups for replaced files, and rolls back touched files if a multi-file installation transaction fails. A second successful installation of the same verified version leaves matching files unchanged.
To return a test profile to the available legacy path, disable AgentTab manually in chrome://extensions and continue using the preserved Chrome Bridge v1.0.1 setup. Do not delete Chrome Bridge files as part of that rollback.
There is no agenttab uninstall command in the current CLI source, and the current installer does not implement an automated v2 removal procedure. Keep the install receipt, native-host manifest, and any listed backups until a supported uninstall path is released. This is intentionally not replaced with an unsafe manual-deletion recipe.
The installer source recognizes host target triples for macOS ARM64 and x86_64, Linux ARM64 and x86_64, and Windows ARM64 and x86_64. Those mappings are implementation support, not a public release promise: no signed v2 artifact matrix is available yet. A public v2 installation is unavailable on every platform until the release gates are complete.