[!IMPORTANT] Surfer-H-CLI has been deprecated and is no longer maintained.

Please use the Models API and Agent API instead. The typed Python/TypeScript clients and CLI now ship as hai-agents — PyPI · npm · SDK docs.

Surfer-H-CLI / Open Surfer-H

🌐 Website | 📖 Tech report | 🤗 Hugging-Face Models | 🏄 Surfer-H product | ☁️ AWS Model Deployment

Introducing the latest range of Holo models: Holo1.5 State-of-the-art Foundational Models for Computer Use Agents

Introduction

The Holo models are H Company’s Action Vision-Language Models (VLMs) and Surfer-H is the agent that enacts them in the real world. Together, they provide a powerful, automated, yet optimized solution to interacting with web interfaces the way we do—setting a goal, taking decisions, re-thinking and re-assessing where needed, and, ultimately, fulfilling everyday tasks. Holo models and Surfer-H have been designed and built to do everything from booking flights, to searching for recipes online, and more.

The Surfer-H-CLI is the command-line interface for running and controlling the Surfer-H agent, allowing you to define tasks, connect to Holo models, and execute web interactions directly from your terminal.

Quick Start

To get started, first generate an API key at: https://portal.hcompany.ai. This API key will allow you to run inference on H company models. Guide: generate an API key

Next, copy the example env variables.

cp .env.example .env

Enter your newly generated HAI_API_KEY in your .env

Or setup globally: Add these to your .zshrc or .bashrc files:

export HAI_API_KEY=...
export HAI_MODEL_URL=...
export HAI_MODEL_NAME=...

Running via the CLI:

./run-on-holo.sh

Running with holo1.5 as localizer (best performance):

./run-on-holo-1-5.sh

Running with the frontend interface:

./launch.sh

This command will automatically start both the Surfer-H backend and the Next.js frontend, making the web interface available at http://localhost:3000.

Holo models

Holo1 and Holo1.5 are Action Vision-Language Models (VLMs) developed by H Company for use in Surfer-H. The Holo models enable the agent to understand and act in digital environments. Holo is built based on 3 core components that shape and determine its behaviour: policy, localizer, and validator. These are defined below:

• Policy: Determines what action should be taken.
• Localizer: Locates elements on the screen—like buttons, text fields, or key UI attributes.
• Validator: Decides whether it succeeded or failed in doing what it set out to do.

Trained on a combination of open-access, synthetic, and self-generated data, Holo enables state-of-the-art (SOTA) performance on the WebVoyager benchmark, offering the best accuracy/cost tradeoff among current models. It also excels in UI localization tasks such as Screenspot, Screenspot-V2, Screenspot-Pro, GroundUI-Web, and our own newly introduced benchmark, WebClick. Holo is optimized for both accuracy and cost-efficiency, making it a strong open-source alternative to existing VLMs. Currently, these models are available for inference:

Note: Use the Inference Model Name from the table above as the value for the HAI_MODEL_NAME environment variable when running the agent.

Frontend Interface

In addition to the command-line interface, Surfer-H includes a modern web frontend that provides an intuitive way to interact with the agent. The frontend offers several advantages over the CLI:

Features

• Task Creation: Simply describe what you want to accomplish in natural language through a web interface
• Real-time Monitoring: Watch your agent complete tasks with live updates
• Trajectory Management: View, replay, and manage automated browsing sequences
• Settings Configuration: Easily customize agent behavior, target URLs, and execution parameters through a UI
• Example Tasks: Get started quickly with pre-configured example prompts

Interface Preview

The Surfer-H web interface showing real-time agent monitoring as it searches for a beef Wellington recipe

For detailed setup instructions, manual installation, and development information, see the Frontend README.

View a sample run

The video below shows Surfer-H in action, demonstrating how the agent completes a real-world task by thinking, reasoning, and browsing the web based on a prompt. This demo (hosted on YouTube) illustrates what to expect when running an agent using the Surfer-H-CLI with the command ./run-on-holo.sh.

Other deployment methods

There are different methods and contexts in which to deploy Holo models, including:

Run the agent locally

If you're serving your own model using vLLM, start the server with:

export HAI_API_KEY=EMPTY
export HAI_MODEL_URL=http://localhost:8082/v1
export HAI_MODEL_NAME=Hcompany/Holo1-7B
vllm serve Hcompany/Holo1-7B --port 8082

You can then run the agent from the Surfer-H-CLI using the following command:

./run-on-holo.sh

Here are the different run settings that may apply based on use and context:

• run-on-holo.sh : Use a Holo mode for navigation and localization, hosted remotely.
• run-on-holo-local.sh : Script with specific instruction for using one or several locally hosted Holo1.
• run-on-holo-val-gpt41.sh : Use remotely-hosted Holo model and GPT-4.1 for validation.

When running vllm, you can leave the HAI_API_KEY empty (or set it to any value), and set HAI_MODEL_URL to http://localhost:PORT using the port where your local vllm instance is running.

The above scripts call the agent like this, with different configurations for the placeholders:

MODEL="<model name for endpoint>"
TASK="Find a beef Wellington recipe with a rating of 4.7 or higher and at least 200 reviews."
URL="https://www.allrecipes.com"

uv run src/surfer_h_cli/surferh.py \
    --task "$TASK" \
    --url "$URL" \
    --max_n_steps 30 \
    --base_url_localization https://<openai-api-compatible-endpoint-such-as-vllm> \
    --model_name_localization $MODEL \
    --temperature_localization 0.0 \
    --base_url_navigation https://<openai-api-compatible-endpoint-such-as-vllm> \
    --model_name_navigation $MODEL \
    --temperature_navigation 0.7 \

Using GPT for Validation

To run run-on-holo-val-gpt41.sh, remember to export your OpenAI API key for validation:

export API_KEY_VALIDATION=${OPENAI_API_KEY}

and define the correct base URL

--base_url_validation https://api.openai.com/v1/

For more information, check out the H.AI Cookbook.

Citation

BibTeX:

@misc{andreux2025surferhmeetsholo1costefficient,
      title={Surfer-H Meets Holo1: Cost-Efficient