Browser profiles

A cloud browser’s saved cookies and storage, so a session starts signed in.

Default profiles

Every user has a default profile per browser flavor (for example chromium): a browser that remembers you across sessions. You upload nothing and track no IDs.

Browser that follows the default profile

{ "id": "acme-browser", "kind": "web", "use_default_browser_profile": true }

• If you have no default yet, the session creates an empty profile and marks it as your default when it starts. Sign in to your sites once (for example in the session’s Agent View) and the state carries forward. Delete it and the next default-profile session starts from a fresh empty default.
• Each session writes its final state back when it ends, under the one-writer rule.
• Name a profile with browser_profile_id or follow the default, not both.

Save state back

A profile named with browser_profile_id is read-only by default: the session discards whatever it changes (new cookies, refreshed tokens, dismissed banners), so its logins age out. Set persist_browser_profile: true to write the final state back when the session ends. Sessions that follow your default profile persist without the flag.

Browser that keeps its profile fresh

{
  "id": "acme-browser",
  "kind": "web",
  "browser_profile_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "persist_browser_profile": true
}

One session writes to a profile at a time. The first session to persist a profile, by flag or as a default-profile session, holds its write lock until it ends. Later sessions asking to persist still start, but read-only, instead of failing. Any number of sessions can load a profile read-only in parallel.

• Last write wins: the session’s final state replaces the stored state.
• Request persistence when creating the session, not when attaching to one.
• If the write-back fails, the session still stops cleanly and the profile keeps its previous state.

Upload your own profile

Upload a profile when you want to bring logins built outside H. You build a Chrome user-data directory (the folder holding cookies, local storage, saved logins, and extensions), zip it, and upload it.

Build a dedicated profile, on Linux, on the runner’s Chromium:

• Never upload your personal Chrome directory (~/Library/Application Support/Google/Chrome on macOS, ~/.config/google-chrome on Linux). It holds every password, token, and history entry you have. Treat the archive as a secret.
• Cookies only carry over from Linux builds. On macOS and Windows, Chrome always encrypts cookies with the OS keychain (Keychain or DPAPI), so the profile loads logged out, with only storage and extensions. No flag changes that: build in Docker.
• Sessions run Chromium 150.0.7871.124. A profile built on a newer version does not load.
• Shut Chromium down cleanly. It writes cookies to disk only on a clean shutdown or an occasional autosave. Killing it (docker stop sends SIGTERM, docker rm -f sends SIGKILL) can lose the logins you just made.

Creating a profile

--password-store=basic makes cookies portable: Chrome encrypts them with a built-in key that the session runner also uses. Without it, the agent starts logged out.

Docker (any OS)

You need Docker. The image tag is pinned to the runner’s Chromium, so do not use :latest.

docker run -d --name agent-profile -p 127.0.0.1:3000:3000 \
  -e CHROME_CLI="--password-store=basic" \
  -v "$HOME/agent-profile:/config" \
  lscr.io/linuxserver/chromium:11e602ae-ls45

# Open http://localhost:3000 and sign in to the sites the agent needs.

# Flush cookies with SIGINT, wait, then remove the container and zip.
docker exec agent-profile pkill -INT -o chromium
sleep 3
docker rm -f agent-profile
cd "$HOME/agent-profile/.config/chromium" && zip -r ~/profile.zip .

Linux Chrome

Use a Chrome no newer than the runner’s. It opens a fresh profile, separate from your everyday one.

google-chrome --user-data-dir="$HOME/agent-profile" --password-store=basic

# Sign in, dismiss cookie banners, install extensions. Quit Chrome cleanly, then:
cd "$HOME/agent-profile" && zip -r ~/profile.zip .

Uploading a profile

1. Initiate the upload

   POST /initiate-upload returns a profile_id, a presigned upload_url, and the upload_fields to send with the file.

   Python

   from hai_agents import Client
   
   client = Client()
   
   upload = client.browser_profiles.initiate_browser_profile_upload()
   
2. Upload the archive to storage

   POST the .zip to upload_url as multipart/form-data, with every entry of upload_fields, unmodified. The archive must be application/zip, at most 1 GB. The URL and fields expire after upload_expires_in seconds, so upload right away.

   Python

   import requests
   
   with open("profile.zip", "rb") as f:
       resp = requests.post(
           upload.upload_url,
           data=upload.upload_fields,
           files={"file": ("profile.zip", f, "application/zip")},
       )
       resp.raise_for_status()
   
3. Complete the upload

   POST /{profile_id}/complete-upload with name, browser_name, and browser_version within 1 day, or the pending upload is deleted. The platform verifies the archive and creates the profile.

   Python

   profile = client.browser_profiles.complete_browser_profile_upload(
       profile_id=upload.profile_id,
       name="acme-prod-login",
       browser_name="chromium",
       browser_version="150",
   )
   print(profile.id)
   

Load it by setting browser_profile_id on the browser, as in Sign in. List, retrieve, or delete your profiles with the browser profile endpoints.

Choose your own default

Promote a profile you curated (for example one you uploaded). You can only mark profiles you created yourself. Profile objects report their status in is_default.

Action	Endpoint
Set (replaces the previous default for that browser)	PUT /browser-profiles/{profile_id}/default
Read	GET /browser-profiles/default
Clear	DELETE /browser-profiles/{profile_id}/default