> ## Documentation Index
> Fetch the complete documentation index at: https://hub.hcompany.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> H Platform has four products: the Agents API (managed computer-use agents, base URL https://agp.eu.hcompany.ai/api/v2 or https://agp.hcompany.ai/api/v2 for the US), the Models API (OpenAI-compatible Holo vision-language models at https://api.hcompany.ai/v1), HoloDesktop CLI (Holo on the user's own desktop), and HoloTab (a free no-code Chrome extension that runs Holo in the user's browser, with recordable routines and schedules).
> Authenticate with a bearer API key from the HAI_API_KEY environment variable. SDKs: `pip install hai-agents` (Python, `from hai_agents import Client`) and `npm install hai-agents` (TypeScript, `import { HaiAgentsClient } from "hai-agents"`). CLI: `hai`.
> Agents do work in a browser or on a desktop; describe the task as an imperative instruction. To run a task quickly, prefer the pre-built agent `h/web-surfer-flash`. Read results from the session's `latest_answer` after it reaches a terminal status.
> Sessions are the unit of work; wait for a terminal status (completed, failed, timed_out, interrupted) before reading the answer. Use webhooks or the `changes` long-poll endpoint to follow progress.

# Changelog

> Notable changes to the Agents API, the hai-agents SDKs, and the hai CLI, by release.

<Update label="1.2.5" description="October 15, 2026">
  **Timing and screenshot controls.** Trade speed for stability per environment. See [Configuration](/agents-api/browser/configuration) and [Create an environment](/agents-api/environments/create#request-body).

  * `settle_s` sets the seconds the agent waits after each action, from `0` to `10`. Browsers default to `1.0`, desktops to `0.5`.
  * `screenshot_max_width` caps a desktop's screenshot width, up to `1920` pixels. `null` keeps the host default. Screenshots are only shrunk, never enlarged.
  * Desktops wait 0.5 s after each action on every host (previously 0.1 s on your machine, 1.0 s in the cloud).

  **Retention follows your privacy settings.** A new session that omits `delete_after_min` keeps its data for the retention period in your privacy settings. A value still deletes it sooner, and `null` adds no expiry beyond that period. Existing sessions keep their policy. See [Create a session](/agents-api/sessions/create).
</Update>

<Update label="1.2.4" description="October 15, 2026">
  **Schedules that stop on their own.** `repeats` caps how many sessions a [schedule](/agents-api/schedules/overview) creates. Each automatic fire that creates a session counts toward `sessions_created`, and the schedule pauses when it reaches `repeats`. Raise `repeats` or set it to `null`, then [resume](/agents-api/schedules/resume), to run more.
</Update>

<Update label="1.2.3" description="October 9, 2026">
  **Self-hosted Holo4 in local mode.** `Inference.self_hosted(url, model="holo4-35b-a3b")` or `model="holo4-27b"` runs the Holo4 harness against your own server. The harness follows the model you name. See [Local mode](/agents-api/local-mode).
</Update>

<Update label="1.2.2" description="October 8, 2026">
  **Local mode on Linux and Windows ARM64.** The local runtime now ships for Linux x64 and Windows ARM64, next to macOS on Apple silicon and Windows x64. See [Local mode](/agents-api/local-mode).

  **Local desktop safety.**

  * Double-Esc cancels the in-flight local desktop session on Windows and Linux, as on macOS.
  * One process drives a desktop at a time: a second one fails with `DesktopBusyError`.
</Update>

<Update label="1.2.1" description="October 7, 2026">
  **Local mode (Python).** `Client.local()` runs the agent on your own machine, with the cloud's sessions API and H's hosted models or your own model server. See [Local mode](/agents-api/local-mode).

  **Filter H's agents.** [List agents](/agents-api/agents/list) takes `reserved`: `true` returns only H's `h/` agents, `false` only your organization's.
</Update>

<Update label="1.2.0" description="September 23, 2026">
  **Holo4 for every agent.**

  * `holo4-27b` and `holo4-35b-a3b` are available to all organizations as the `model` of any agent or subagent.
  * New agents that leave `model` unset run on `holo4-27b`.
  * Holo4 honors every `reasoning_effort` level and defaults to `medium`.

  **SDK 1.2.0.** `hai-agents` 1.2.0 (Python and TypeScript) ships with this release.
</Update>

<Update label="1.0.11" description="September 22, 2026">
  **Out-of-credit failures.**

  * A session whose organization has no plan usage or credit left ends `failed` with `error_code: insufficient_credit` (previously reported as `internal`).
  * Message: "The organization has no credit left to pay for the session's model calls."
  * Top up credit or wait for the plan's allowance to renew, then retry. See [Error codes](/agents-api/errors#error-codes).
</Update>

<Update label="1.0.8" description="September 15, 2026">
  **Session files.** [List](/agents-api/sessions/list-files), [read](/agents-api/sessions/read-file), or [write](/agents-api/sessions/write-file) files on a cloud browser's machine while a session runs.

  * Base64 bodies, capped at 8 MiB, confined to `~/Downloads`.
  * Addressed by the browser session id, published on the events stream as `RunnerSessionEvent`.
  * Also exposed as `list_files` / `read_file` / `write_file` on the [MCP server](/agents-api/mcp).

  **Lazy browsers.** `lazy: true` on a Browser environment starts the cloud browser on the agent's first browser action, not at session start. The first turn no longer waits for a boot, and an unused browser never starts. See [Configuration](/agents-api/browser/configuration).

  **File transfer events.** Every file the agent moves in or out of its browser is reported as a `FileTransferEvent` with `direction` (`download` or `upload`), `path`, and `size_bytes`. See [Event types](/agents-api/sessions/events#event-types-type).

  **Bounded tool results.** Oversized tool output is cut to a 16 KiB head/tail preview before it reaches the model and the events stream. `tool_result` events carry `truncated`, plus `output_artifact_path` when a code sandbox holds the full text. See [Agent activity](/agents-api/sessions/events#agent-activity-agenteventdata).

  **Session activity timestamp.** [List](/agents-api/sessions/list) summaries carry `last_activity_at`, when the session's latest event was ingested, to spot which live sessions are moving.
</Update>

<Update label="1.0.7" description="July 16, 2026">
  **Session retention controls.** `delete_after_min` deletes a finished session after a delay, and `delete_screenshot_after_min` expires its screenshots sooner. Both default to 30 days, and `null` keeps data indefinitely. See [Create a session](/agents-api/sessions/create).

  **Faster local desktop.** Screenshots are downscaled and recompressed on your machine before upload, cutting per-step latency on high-resolution displays. Tune with `--max-width`, `--image-format`, and `--quality` on `hai local desktop`. See [Local control](/agents-api/local-control).

  **Sturdier local control (Python SDK and CLI).**

  * `hai doctor` diagnoses login, platform access, and local-control prerequisites, with fix-it hints.
  * `hai local stop` (or double-Esc during a desktop turn) cancels the in-flight local session. Sessions auto-cancel when your process exits, and auto-started ones get default `max_steps` / `max_time_s` budgets.
  * On macOS, missing Accessibility or Screen Recording permissions fail fast at startup.
</Update>

<Update label="1.0.6" description="July 9, 2026">
  **Local control.** Set an environment's `host` to `user_device` and run a session from the Python SDK: the agent drives the browser or desktop on your own machine. It launches Chrome and connects your machine to H automatically. See [Local control](/agents-api/local-control).

  **Persistent browser profiles.** See [Persisting state back](/agents-api/browser/profiles#persisting-state-back-into-the-profile).

  * `persist_browser_profile: true` with `browser_profile_id` writes the session's final browser state (cookies, storage) back into the profile, so each run refreshes it for the next.
  * An exclusive write lock allows one persisting session per profile. Concurrent read-only use is unaffected.
  * When the lock is held, a new persist session starts read-only instead of failing.

  **Default browser profiles.** See [Default profiles](/agents-api/browser/profiles#default-profiles).

  * `use_default_browser_profile: true` loads your default profile (auto-created empty on first use) and saves the final state back when the session ends (best-effort: concurrent sessions run read-only).
  * Promote a curated profile with [`PUT /browser-profiles/{profile_id}/default`](/agents-api/browser-profiles/set-default).
  * Profiles report `is_default`. The [get-default](/agents-api/browser-profiles/get-default) and [unset-default](/agents-api/browser-profiles/unset-default) endpoints complete the set.
</Update>

<Update label="1.0.5" description="July 6, 2026">
  **Scheduled sessions.** Cron schedules start a session on each fire: five-field expressions in an IANA timezone, with pause/resume, manual trigger, and a run history showing whether each fire created a session or was skipped. See [Schedules](/agents-api/schedules/overview).

  **Managed proxies.** See [Proxy](/agents-api/browser/proxy).

  * Browser environments can egress through an H-provisioned proxy: `network.managed_proxy` with a `pool` (`residential` or `datacenter`), an optional `country`, and `sticky` to keep one exit IP per session.
  * The platform resolves the provider and credentials server-side, so you never handle them.
  * Mutually exclusive with `network.proxy_url`.

  **Webhook delivery health.** Webhooks report `last_delivery_status`, `last_delivery_error`, `last_delivery_at`, `last_success_at`, and `consecutive_failures`. Poll [retrieve](/agents-api/webhooks/retrieve) to monitor an endpoint before it gets disabled. See [Webhooks](/agents-api/webhooks/overview).
</Update>

<Update label="1.0.4" description="July 3, 2026">
  **Queue sessions instead of 429.** Over-quota creates are accepted as `queued` and start automatically, oldest first, as slots free up. Queued sessions fire webhooks on every transition and can be cancelled. `queue: false` on [create](/agents-api/sessions/create) keeps the old `429`. See [Queued sessions](/agents-api/plans-and-limits#queued-sessions).

  **Granular webhook events, retries, ping, secret rotation.** See [Webhooks](/agents-api/webhooks/overview).

  * Subscribe to specific types like `session.completed` or `session.awaiting_tool_results` instead of the `session.status_updated` firehose ([event catalog](/agents-api/webhooks/events)).
  * Failed deliveries retry with backoff, and the platform disables endpoints that keep failing.
  * [Ping](/agents-api/webhooks/ping) an endpoint or [rotate its secret](/agents-api/webhooks/rotate) without downtime.

  **Machine-readable failures.** Failed sessions carry an `error_code` (`environment_error`, `no_answer`, `answer_validation`, `timeout`, `internal`) next to the human-readable `error`, and every answer reports the agent's self-assessed `outcome` (`success`, `partial`, `infeasible`, `blocked`). Build retry logic on codes, not strings. See [Session failures](/agents-api/errors#session-failures).
</Update>

<Update label="1.0.3" description="July 1, 2026">
  **Browser `headless` option.** Browser environments accept `headless: true` to run without a visible window (default `false`). See [Configuration](/agents-api/browser/configuration).

  Registry packages skipped this version. Its changes shipped in the 1.0.4 packages.
</Update>

<Update label="1.0.2" description="July 1, 2026">
  **Browse the `h/` catalog without an API key.** Listing agents, skills, and environments no longer needs authentication for the reserved `h/` catalog. Authenticated calls also return your organization's entries.

  **CLI agent picker.** `hai run` without `--agent` lists the live agent catalog and prompts for a choice, instead of assuming a default agent.
</Update>

<Update label="1.0.1" description="June 29, 2026">
  **Nested Browser `mode`.** A Browser's `mode` is an object keyed by `type`, so viewport and text settings live with their mode. The old flat shape (`"mode": "visual"` with sibling `width`, `height`, `page_chars`) still parses. See [Modes](/agents-api/browser/configuration#modes).

  * `visual` (default): `{"type": "visual", "width": 1200, "height": 1200, "markdown": false}`. `markdown: true` adds the page's text to each screenshot (replaces the old `multimodal` mode).
  * `text`: `{"type": "text", "chunk_size": 20000}`. `chunk_size` replaces the old top-level `page_chars`.
</Update>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.