Browser profiles

A browser profile is a cloud browser’s saved state (cookies, local storage, session data), so the agent starts a session already signed in. Profiles belong to your organization: any agent in it can load one, and they persist until you delete them. Use a vault instead when the agent should sign in with credentials. A profile carries an existing logged-in session forward. A local browser uses its own Chrome profile instead.

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 }

First use creates it. 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 live view) and the state carries forward.
Sessions save back automatically. Each session writes its final state back when it ends. Best-effort: when several default-profile sessions run at once, the first to start writes and the others run read-only. They never fail over it.
Exclusive with browser_profile_id. Name a profile or follow the default, not both.

Auto-created defaults appear in your profile list as default-<browser>-.... Delete one and the next default-profile session starts from a fresh empty default.

Choosing 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`

Persisting state back into the profile

A profile named with browser_profile_id is read-only by default: the session discards whatever the run 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.

Browser that keeps its profile fresh

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

One writer at a time. A persisting session holds an exclusive write lock until it ends. A second session asking to persist the same profile still starts, but read-only. Any number of sessions can load a profile read-only in parallel. For a run that must persist (like a scheduled login-refresh job), check the session’s effective persist state after creation and reschedule if it was downgraded.
Last write wins. The session’s final state replaces the stored state. It is not merged.
Decided at create time. Request persistence when creating the session, not when attaching to one.
Best-effort on stop. If the write-back fails, the session still stops cleanly and the profile keeps its previous state.

Sessions that follow your default profile persist without the flag.

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.

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)
Linux Chrome

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 .

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 .

The same steps with desktop Chrome on macOS or Windows keep storage and extensions, but not cookies.

Uploading a profile

The archive goes straight to object storage through a presigned URL, never through the Agents API.

Initiate the upload

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

INIT=$(curl -s -X POST https://agp.eu.hcompany.ai/api/v2/browser-profiles/initiate-upload \
  -H "Authorization: Bearer $HAI_API_KEY")
PROFILE_ID=$(echo "$INIT" | jq -r .profile_id)
UPLOAD_URL=$(echo "$INIT" | jq -r .upload_url)

from hai_agents import Client

client = Client()

upload = client.browser_profiles.initiate_browser_profile_upload()

import { HaiAgentsClient } from "hai-agents";

const client = new HaiAgentsClient();

const upload = await client.browserProfiles.initiateBrowserProfileUpload();

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.

args=()
while IFS= read -r line; do
  args+=(--form-string "$line")
done <<< "$(echo "$INIT" | jq -r '.upload_fields | to_entries[] | "\(.key)=\(.value)"')"

curl -sS --fail-with-body -w "upload: HTTP %{http_code}\n" \
  -X POST "$UPLOAD_URL" "${args[@]}" -F "file=@profile.zip"

# Healthy upload will return `upload: HTTP 204`

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()

import { readFileSync } from "fs";

const form = new FormData();
for (const [key, value] of Object.entries(upload.uploadFields)) {
  form.append(key, value as string);
}
form.append("file", new Blob([readFileSync("profile.zip")]), "profile.zip");
const resp = await fetch(upload.uploadUrl, { method: "POST", body: form });
if (!resp.ok) throw new Error(`upload failed: ${resp.status}`);

Complete the upload

POST /{profile_id}/complete-upload with name, browser_name, and browser_version within 1 day. The platform verifies the archive and creates the profile. It deletes a pending upload after 1 day.

curl -X POST "https://agp.eu.hcompany.ai/api/v2/browser-profiles/$PROFILE_ID/complete-upload" \
  -H "Authorization: Bearer $HAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "acme-prod-login", "browser_name": "chromium", "browser_version": "150"}'

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)

const profile = await client.browserProfiles.completeBrowserProfileUpload({
  profileId: upload.profileId,
  name: "acme-prod-login",
  browserName: "chromium",
  browserVersion: "150",
});
console.log(profile.id);

Load it with browser_profile_id on the browser environment. List, retrieve, or delete your profiles with the browser profile endpoints. Related: Vaults, Configure the browser.

Get started

Concepts

Browser and desktop

Integrations

Guides

Operate

Default profiles

Choosing your own default

Persisting state back into the profile

Upload your own profile

Creating a profile

Uploading a profile

​Default profiles

​Choosing your own default

​Persisting state back into the profile

​Upload your own profile

​Creating a profile

​Uploading a profile

Default profiles

Choosing your own default

Persisting state back into the profile

Upload your own profile

Creating a profile

Uploading a profile