agent-browser-priv 0.27.3-priv.3

package/scripts/sync-version.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+/**
+ * Syncs the version from package.json to all other config files.
+ * Run this script before building or releasing.
+ */
+
+import { execSync } from "child_process";
+import { readFileSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const rootDir = join(__dirname, "..");
+const cliDir = join(rootDir, "cli");
+
+// Read version from package.json (single source of truth)
+const packageJson = JSON.parse(
+  readFileSync(join(rootDir, "package.json"), "utf-8")
+);
+const version = packageJson.version;
+
+console.log(`Syncing version ${version} to all config files...`);
+
+// Update Cargo.toml
+const cargoTomlPath = join(cliDir, "Cargo.toml");
+let cargoToml = readFileSync(cargoTomlPath, "utf-8");
+const cargoVersionRegex = /^version\s*=\s*"[^"]*"/m;
+const newCargoVersion = `version = "${version}"`;
+
+let cargoTomlUpdated = false;
+if (cargoVersionRegex.test(cargoToml)) {
+  const oldMatch = cargoToml.match(cargoVersionRegex)?.[0];
+  if (oldMatch !== newCargoVersion) {
+    cargoToml = cargoToml.replace(cargoVersionRegex, newCargoVersion);
+    writeFileSync(cargoTomlPath, cargoToml);
+    console.log(`  Updated cli/Cargo.toml: ${oldMatch} -> ${newCargoVersion}`);
+    cargoTomlUpdated = true;
+  } else {
+    console.log(`  cli/Cargo.toml already up to date`);
+  }
+} else {
+  console.error("  Could not find version field in cli/Cargo.toml");
+  process.exit(1);
+}
+
+// Update packages/dashboard/package.json
+const dashboardPkgPath = join(rootDir, "packages", "dashboard", "package.json");
+const dashboardPkg = JSON.parse(readFileSync(dashboardPkgPath, "utf-8"));
+if (dashboardPkg.version !== version) {
+  const oldVersion = dashboardPkg.version;
+  dashboardPkg.version = version;
+  writeFileSync(dashboardPkgPath, JSON.stringify(dashboardPkg, null, 2) + "\n");
+  console.log(`  Updated packages/dashboard/package.json: ${oldVersion} -> ${version}`);
+} else {
+  console.log(`  packages/dashboard/package.json already up to date`);
+}
+
+// Update Cargo.lock to match Cargo.toml
+if (cargoTomlUpdated) {
+  try {
+    execSync("cargo update -p agent-browser --offline", {
+      cwd: cliDir,
+      stdio: "pipe",
+    });
+    console.log(`  Updated cli/Cargo.lock`);
+  } catch {
+    // --offline may fail if package not in cache, try without it
+    try {
+      execSync("cargo update -p agent-browser", {
+        cwd: cliDir,
+        stdio: "pipe",
+      });
+      console.log(`  Updated cli/Cargo.lock`);
+    } catch (e) {
+      console.error(`  Warning: Could not update Cargo.lock: ${e.message}`);
+    }
+  }
+}
+
+console.log("Version sync complete.");

package/scripts/windows-debug/provision.sh

@@ -0,0 +1,220 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+INSTANCE_FILE="$SCRIPT_DIR/.instance"
+NAME_PREFIX="agent-browser-debug"
+INSTANCE_TYPE="${INSTANCE_TYPE:-t3.xlarge}"
+
+if [[ -f "$INSTANCE_FILE" ]]; then
+  echo "Error: Instance already provisioned. See $INSTANCE_FILE"
+  echo "Run ./scripts/windows-debug/start.sh to start it, or delete .instance to re-provision."
+  exit 1
+fi
+
+REGION=$(aws configure get region 2>/dev/null || echo "")
+if [[ -z "$REGION" ]]; then
+  echo "Error: No AWS region configured. Run: aws configure set region us-east-1"
+  exit 1
+fi
+
+echo "Provisioning Windows debug instance in $REGION..."
+
+# --- IAM Role for SSM ---
+ROLE_NAME="${IAM_ROLE_NAME:-$NAME_PREFIX-ssm-role}"
+PROFILE_NAME="${INSTANCE_PROFILE_NAME:-$NAME_PREFIX-instance-profile}"
+
+if aws iam get-instance-profile --instance-profile-name "$PROFILE_NAME" &>/dev/null; then
+  echo "Instance profile $PROFILE_NAME already exists, reusing."
+else
+  echo "Instance profile $PROFILE_NAME not found. Creating IAM resources..."
+
+  if ! aws iam get-role --role-name "$ROLE_NAME" &>/dev/null; then
+    echo "Creating IAM role: $ROLE_NAME"
+    if ! aws iam create-role \
+      --role-name "$ROLE_NAME" \
+      --assume-role-policy-document '{
+        "Version": "2012-10-17",
+        "Statement": [{
+          "Effect": "Allow",
+          "Principal": {"Service": "ec2.amazonaws.com"},
+          "Action": "sts:AssumeRole"
+        }]
+      }' \
+      --no-cli-pager; then
+
+      echo ""
+      echo "Error: Failed to create IAM role (see error above)."
+      echo ""
+      echo "Ask an IAM admin to create the following, then re-run with:"
+      echo "  INSTANCE_PROFILE_NAME=<name> ./scripts/windows-debug/provision.sh"
+      echo ""
+      echo "What the admin needs to create:"
+      echo "  1. IAM Role: $ROLE_NAME"
+      echo "     - Trusted entity: EC2 (ec2.amazonaws.com)"
+      echo "     - Attached policy: AmazonSSMManagedInstanceCore"
+      echo "  2. Instance Profile: $PROFILE_NAME"
+      echo "     - With the above role added to it"
+      echo ""
+      echo "Or run these commands with an account that has iam:CreateRole permission:"
+      echo ""
+      echo "  aws iam create-role --role-name $ROLE_NAME \\"
+      echo "    --assume-role-policy-document '{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"ec2.amazonaws.com\"},\"Action\":\"sts:AssumeRole\"}]}'"
+      echo ""
+      echo "  aws iam attach-role-policy --role-name $ROLE_NAME \\"
+      echo "    --policy-arn arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore"
+      echo ""
+      echo "  aws iam create-instance-profile --instance-profile-name $PROFILE_NAME"
+      echo ""
+      echo "  aws iam add-role-to-instance-profile \\"
+      echo "    --instance-profile-name $PROFILE_NAME --role-name $ROLE_NAME"
+      exit 1
+    fi
+
+    aws iam attach-role-policy \
+      --role-name "$ROLE_NAME" \
+      --policy-arn arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore
+  else
+    echo "IAM role $ROLE_NAME already exists."
+  fi
+
+  echo "Creating instance profile: $PROFILE_NAME"
+  aws iam create-instance-profile --instance-profile-name "$PROFILE_NAME" --no-cli-pager
+  aws iam add-role-to-instance-profile \
+    --instance-profile-name "$PROFILE_NAME" \
+    --role-name "$ROLE_NAME"
+  echo "Waiting for instance profile propagation..."
+  sleep 10
+fi
+
+# --- Security Group (no inbound rules) ---
+VPC_ID=$(aws ec2 describe-vpcs --filters "Name=isDefault,Values=true" --query "Vpcs[0].VpcId" --output text)
+if [[ "$VPC_ID" == "None" || -z "$VPC_ID" ]]; then
+  echo "Error: No default VPC found. Create one with: aws ec2 create-default-vpc"
+  exit 1
+fi
+
+SG_NAME="$NAME_PREFIX-sg"
+SG_ID=$(aws ec2 describe-security-groups \
+  --filters "Name=group-name,Values=$SG_NAME" "Name=vpc-id,Values=$VPC_ID" \
+  --query "SecurityGroups[0].GroupId" --output text 2>/dev/null || echo "None")
+
+if [[ "$SG_ID" == "None" || -z "$SG_ID" ]]; then
+  echo "Creating security group: $SG_NAME"
+  SG_ID=$(aws ec2 create-security-group \
+    --group-name "$SG_NAME" \
+    --description "agent-browser Windows debug instance (SSM only, no inbound)" \
+    --vpc-id "$VPC_ID" \
+    --query "GroupId" --output text)
+
+  # Revoke default egress isn't needed; SSM requires outbound HTTPS.
+  # No inbound rules -- SSM uses outbound connections only.
+else
+  echo "Security group $SG_NAME ($SG_ID) already exists, reusing."
+fi
+
+# --- AMI (latest Windows Server 2022) ---
+AMI_ID=$(aws ssm get-parameter \
+  --name "/aws/service/ami-windows-latest/Windows_Server-2022-English-Full-Base" \
+  --query "Parameter.Value" --output text)
+echo "Using AMI: $AMI_ID (Windows Server 2022)"
+
+# --- UserData bootstrap script ---
+USERDATA_FILE=$(mktemp)
+trap "rm -f $USERDATA_FILE" EXIT
+
+cat > "$USERDATA_FILE" <<'PWSH'
+<powershell>
+$ErrorActionPreference = "Continue"
+$logFile = "C:\bootstrap.log"
+
+function Log($msg) {
+    $ts = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
+    "$ts  $msg" | Tee-Object -FilePath $logFile -Append
+}
+
+Log "--- Bootstrap starting ---"
+
+# Install Git
+Log "Installing Git..."
+$gitInstaller = "$env:TEMP\git-installer.exe"
+Invoke-WebRequest -Uri "https://github.com/git-for-windows/git/releases/download/v2.47.1.windows.2/Git-2.47.1.2-64-bit.exe" -OutFile $gitInstaller
+Start-Process -FilePath $gitInstaller -ArgumentList "/VERYSILENT /NORESTART /NOCANCEL /SP- /CLOSEAPPLICATIONS /RESTARTAPPLICATIONS /COMPONENTS=`"icons,ext\reg\shellhere,assoc,assoc_sh`"" -Wait
+$env:PATH = "C:\Program Files\Git\cmd;$env:PATH"
+[Environment]::SetEnvironmentVariable("PATH", "C:\Program Files\Git\cmd;$([Environment]::GetEnvironmentVariable('PATH', 'Machine'))", "Machine")
+Log "Git installed: $(git --version)"
+
+# Install Rust
+Log "Installing Rust..."
+$rustupInit = "$env:TEMP\rustup-init.exe"
+Invoke-WebRequest -Uri "https://win.rustup.rs/x86_64" -OutFile $rustupInit
+Start-Process -FilePath $rustupInit -ArgumentList "-y --default-toolchain stable" -Wait
+$env:PATH = "$env:USERPROFILE\.cargo\bin;$env:PATH"
+[Environment]::SetEnvironmentVariable("PATH", "$env:USERPROFILE\.cargo\bin;$([Environment]::GetEnvironmentVariable('PATH', 'Machine'))", "Machine")
+Log "Rust installed: $(rustc --version)"
+
+# Install MSVC build tools (required for Rust on Windows)
+Log "Installing Visual Studio Build Tools..."
+$vsInstaller = "$env:TEMP\vs_buildtools.exe"
+Invoke-WebRequest -Uri "https://aka.ms/vs/17/release/vs_buildtools.exe" -OutFile $vsInstaller
+Start-Process -FilePath $vsInstaller -ArgumentList "--quiet --wait --norestart --nocache --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended" -Wait
+Log "Build tools installed."
+
+# Clone repo
+Log "Cloning agent-browser..."
+git clone https://github.com/vercel-labs/agent-browser.git C:\agent-browser
+Set-Location C:\agent-browser
+Log "Repo cloned."
+
+# Build CLI
+Log "Building agent-browser CLI..."
+cargo build --release --manifest-path cli\Cargo.toml
+Log "Build complete."
+
+# Install Chrome
+Log "Installing Chrome via agent-browser..."
+.\cli\target\release\agent-browser.exe install
+Log "Chrome installed."
+
+Log "--- Bootstrap complete ---"
+</powershell>
+PWSH
+
+# --- Launch instance ---
+echo "Launching $INSTANCE_TYPE instance..."
+INSTANCE_ID=$(aws ec2 run-instances \
+  --image-id "$AMI_ID" \
+  --instance-type "$INSTANCE_TYPE" \
+  --iam-instance-profile "Name=$PROFILE_NAME" \
+  --security-group-ids "$SG_ID" \
+  --user-data "file://$USERDATA_FILE" \
+  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":80,"VolumeType":"gp3"}}]' \
+  --tag-specifications "ResourceType=instance,Tags=[{Key=Name,Value=$NAME_PREFIX}]" \
+  --metadata-options "HttpTokens=required" \
+  --query "Instances[0].InstanceId" --output text)
+
+echo "Instance launched: $INSTANCE_ID"
+
+# Save instance config
+cat > "$INSTANCE_FILE" <<EOF
+INSTANCE_ID=$INSTANCE_ID
+REGION=$REGION
+EOF
+
+echo "Waiting for instance to enter running state..."
+aws ec2 wait instance-running --instance-ids "$INSTANCE_ID"
+echo "Instance is running."
+
+echo ""
+echo "Instance $INSTANCE_ID is booting and bootstrapping (Rust, Git, Chrome)."
+echo "Bootstrap takes ~15-20 minutes on first boot."
+echo ""
+echo "Check bootstrap progress:"
+echo "  ./scripts/windows-debug/run.sh \"Get-Content C:\\bootstrap.log\""
+echo ""
+echo "Once ready, sync your branch and start debugging:"
+echo "  ./scripts/windows-debug/sync.sh"
+echo "  ./scripts/windows-debug/run.sh \"cd C:\\agent-browser && cargo test\""
+echo ""
+echo "Stop when done to save costs:"
+echo "  ./scripts/windows-debug/stop.sh"

package/scripts/windows-debug/run.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+INSTANCE_FILE="$SCRIPT_DIR/.instance"
+
+if [[ ! -f "$INSTANCE_FILE" ]]; then
+  echo "Error: No instance provisioned. Run ./scripts/windows-debug/provision.sh first."
+  exit 1
+fi
+
+if [[ $# -eq 0 ]]; then
+  echo "Usage: ./scripts/windows-debug/run.sh \"<powershell-command>\""
+  echo ""
+  echo "Examples:"
+  echo "  ./scripts/windows-debug/run.sh \"cd C:\\agent-browser && cargo test\""
+  echo "  ./scripts/windows-debug/run.sh \"Get-Content C:\\bootstrap.log\""
+  echo "  ./scripts/windows-debug/run.sh \"cd C:\\agent-browser && cargo test e2e -- --ignored --test-threads=1\""
+  exit 1
+fi
+
+source "$INSTANCE_FILE"
+export AWS_DEFAULT_REGION="$REGION"
+
+COMMAND="$*"
+
+PARAMS_FILE=$(mktemp)
+trap "rm -f $PARAMS_FILE" EXIT
+
+python3 -c '
+import json, sys
+path_setup = "$env:PATH = \"$env:USERPROFILE\\.cargo\\bin;C:\\Program Files\\Git\\cmd;$env:PATH\""
+cmd = path_setup + "\n" + sys.argv[1]
+json.dump({"commands": [cmd]}, open(sys.argv[2], "w"))
+' "$COMMAND" "$PARAMS_FILE"
+
+COMMAND_ID=$(aws ssm send-command \
+  --instance-ids "$INSTANCE_ID" \
+  --document-name "AWS-RunPowerShellScript" \
+  --parameters "file://$PARAMS_FILE" \
+  --timeout-seconds 3600 \
+  --query "Command.CommandId" --output text)
+
+echo "Command sent (ID: $COMMAND_ID). Waiting..." >&2
+
+while true; do
+  RESULT=$(aws ssm get-command-invocation \
+    --command-id "$COMMAND_ID" \
+    --instance-id "$INSTANCE_ID" \
+    --output json 2>&1) || true
+
+  STATUS=$(echo "$RESULT" | python3 -c "
+import sys, json
+try:
+    print(json.loads(sys.stdin.read()).get('Status', 'Unknown'))
+except:
+    print('Pending')
+" 2>/dev/null)
+
+  case "$STATUS" in
+    Success)
+      echo "$RESULT" | python3 -c "
+import sys, json
+r = json.loads(sys.stdin.read())
+out = r.get('StandardOutputContent', '').rstrip()
+err = r.get('StandardErrorContent', '').rstrip()
+if out:
+    print(out)
+if err:
+    print(err, file=sys.stderr)
+"
+      exit 0
+      ;;
+    Failed|TimedOut|Cancelled)
+      echo "$RESULT" | python3 -c "
+import sys, json
+r = json.loads(sys.stdin.read())
+out = r.get('StandardOutputContent', '').rstrip()
+err = r.get('StandardErrorContent', '').rstrip()
+if out:
+    print(out)
+if err:
+    print(err, file=sys.stderr)
+"
+      echo "Command $STATUS." >&2
+      exit 1
+      ;;
+    *)
+      sleep 3
+      ;;
+  esac
+done

package/scripts/windows-debug/start.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+INSTANCE_FILE="$SCRIPT_DIR/.instance"
+
+if [[ ! -f "$INSTANCE_FILE" ]]; then
+  echo "Error: No instance provisioned. Run ./scripts/windows-debug/provision.sh first."
+  exit 1
+fi
+
+source "$INSTANCE_FILE"
+export AWS_DEFAULT_REGION="$REGION"
+
+STATE=$(aws ec2 describe-instances \
+  --instance-ids "$INSTANCE_ID" \
+  --query "Reservations[0].Instances[0].State.Name" --output text)
+
+if [[ "$STATE" == "running" ]]; then
+  echo "Instance $INSTANCE_ID is already running."
+else
+  echo "Starting instance $INSTANCE_ID..."
+  aws ec2 start-instances --instance-ids "$INSTANCE_ID" --no-cli-pager
+  echo "Waiting for running state..."
+  aws ec2 wait instance-running --instance-ids "$INSTANCE_ID"
+  echo "Instance is running."
+fi
+
+echo "Waiting for SSM agent connectivity..."
+for i in $(seq 1 30); do
+  SSM_STATUS=$(aws ssm describe-instance-information \
+    --filters "Key=InstanceIds,Values=$INSTANCE_ID" \
+    --query "InstanceInformationList[0].PingStatus" --output text 2>/dev/null || echo "None")
+  if [[ "$SSM_STATUS" == "Online" ]]; then
+    echo "SSM agent is online. Ready for commands."
+    echo "  ./scripts/windows-debug/run.sh \"your-command-here\""
+    exit 0
+  fi
+  sleep 10
+done
+
+echo "Warning: SSM agent not online after 5 minutes. The instance may still be booting."
+echo "Try again in a minute: ./scripts/windows-debug/run.sh \"hostname\""

package/scripts/windows-debug/stop.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+INSTANCE_FILE="$SCRIPT_DIR/.instance"
+
+if [[ ! -f "$INSTANCE_FILE" ]]; then
+  echo "Error: No instance provisioned. Nothing to stop."
+  exit 1
+fi
+
+source "$INSTANCE_FILE"
+export AWS_DEFAULT_REGION="$REGION"
+
+STATE=$(aws ec2 describe-instances \
+  --instance-ids "$INSTANCE_ID" \
+  --query "Reservations[0].Instances[0].State.Name" --output text)
+
+if [[ "$STATE" == "stopped" ]]; then
+  echo "Instance $INSTANCE_ID is already stopped."
+  exit 0
+fi
+
+echo "Stopping instance $INSTANCE_ID..."
+aws ec2 stop-instances --instance-ids "$INSTANCE_ID" --no-cli-pager
+echo "Waiting for stopped state..."
+aws ec2 wait instance-stopped --instance-ids "$INSTANCE_ID"
+echo "Instance stopped. No compute charges while stopped (storage only: ~$0.64/mo)."

package/scripts/windows-debug/sync.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+RUN="$SCRIPT_DIR/run.sh"
+
+BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "main")
+REMOTE_URL=$(git remote get-url origin 2>/dev/null || echo "https://github.com/vercel-labs/agent-browser.git")
+
+echo "Syncing branch '$BRANCH' on Windows instance..."
+
+"$RUN" "
+cd C:\agent-browser
+git remote set-url origin '$REMOTE_URL'
+git fetch origin
+git checkout -B '$BRANCH' 'origin/$BRANCH'
+git log -1 --oneline
+"
+
+echo ""
+echo "Branch synced. Rebuilding..."
+
+"$RUN" "
+cd C:\agent-browser
+cargo build --release --manifest-path cli\Cargo.toml
+Write-Host 'Build complete.'
+"

package/skill-data/agentcore/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: agentcore
+description: Run agent-browser on AWS Bedrock AgentCore cloud browsers. Use when the user wants to use AgentCore, run browser automation on AWS, use a cloud browser with AWS credentials, or needs a managed browser session backed by AWS infrastructure. Triggers include "use agentcore", "run on AWS", "cloud browser with AWS", "bedrock browser", "agentcore session", or any task requiring AWS-hosted browser automation.
+allowed-tools: Bash(agent-browser:*), Bash(npx agent-browser:*)
+---
+
+# AWS Bedrock AgentCore
+
+Run agent-browser on cloud browser sessions hosted by AWS Bedrock AgentCore. All standard agent-browser commands work identically; the only difference is where the browser runs.
+
+## Setup
+
+Credentials are resolved automatically:
+
+1. Environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, optionally `AWS_SESSION_TOKEN`)
+2. AWS CLI fallback (`aws configure export-credentials`), which supports SSO, IAM roles, and named profiles
+
+No additional setup is needed if the user already has working AWS credentials.
+
+## Core Workflow
+
+```bash
+# Open a page on an AgentCore cloud browser
+agent-browser -p agentcore open https://example.com
+
+# Everything else is the same as local Chrome
+agent-browser snapshot -i
+agent-browser click @e1
+agent-browser screenshot page.png
+agent-browser close
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `AGENTCORE_REGION` | AWS region | `us-east-1` |
+| `AGENTCORE_BROWSER_ID` | Browser identifier | `aws.browser.v1` |
+| `AGENTCORE_PROFILE_ID` | Persistent browser profile (cookies, localStorage) | (none) |
+| `AGENTCORE_SESSION_TIMEOUT` | Session timeout in seconds | `3600` |
+| `AWS_PROFILE` | AWS CLI profile for credential resolution | `default` |
+
+## Persistent Profiles
+
+Use `AGENTCORE_PROFILE_ID` to persist browser state across sessions. This is useful for maintaining login sessions:
+
+```bash
+# First run: log in
+AGENTCORE_PROFILE_ID=my-app agent-browser -p agentcore open https://app.example.com/login
+agent-browser snapshot -i
+agent-browser fill @e1 "user@example.com"
+agent-browser fill @e2 "password"
+agent-browser click @e3
+agent-browser close
+
+# Future runs: already authenticated
+AGENTCORE_PROFILE_ID=my-app agent-browser -p agentcore open https://app.example.com/dashboard
+```
+
+## Live View
+
+When a session starts, AgentCore prints a Live View URL to stderr. Open it in a browser to watch the session in real time from the AWS Console:
+
+```
+Session: abc123-def456
+Live View: https://us-east-1.console.aws.amazon.com/bedrock-agentcore/browser/aws.browser.v1/session/abc123-def456#
+```
+
+## Region Selection
+
+```bash
+# Default: us-east-1
+agent-browser -p agentcore open https://example.com
+
+# Explicit region
+AGENTCORE_REGION=eu-west-1 agent-browser -p agentcore open https://example.com
+```
+
+## Credential Patterns
+
+```bash
+# Explicit credentials (CI/CD, scripts)
+export AWS_ACCESS_KEY_ID=AKIA...
+export AWS_SECRET_ACCESS_KEY=...
+agent-browser -p agentcore open https://example.com
+
+# SSO (interactive)
+aws sso login --profile my-profile
+AWS_PROFILE=my-profile agent-browser -p agentcore open https://example.com
+
+# IAM role / default credential chain
+agent-browser -p agentcore open https://example.com
+```
+
+## Using with AGENT_BROWSER_PROVIDER
+
+Set the provider via environment variable to avoid passing `-p agentcore` on every command:
+
+```bash
+export AGENT_BROWSER_PROVIDER=agentcore
+export AGENTCORE_REGION=us-east-2
+
+agent-browser open https://example.com
+agent-browser snapshot -i
+agent-browser click @e1
+agent-browser close
+```
+
+## Common Issues
+
+**"Failed to run aws CLI"** means AWS CLI is not installed or not in PATH. Either install it or set `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` directly.
+
+**"AWS CLI failed: ... Run 'aws sso login'"** means SSO credentials have expired. Run `aws sso login` to refresh them.
+
+**Session timeout:** The default is 3600 seconds (1 hour). For longer tasks, increase with `AGENTCORE_SESSION_TIMEOUT=7200`.