{"id":49901233,"url":"https://github.com/hcompai/surfer-h-cli","last_synced_at":"2026-05-16T06:29:30.814Z","repository":{"id":303567270,"uuid":"1015956284","full_name":"hcompai/surfer-h-cli","owner":"hcompai","description":"Run Surfer-H agents powered by Holo1 using the Surfer-H-CLI. Includes example tasks, scripts, and configurations.","archived":false,"fork":false,"pushed_at":"2025-09-22T18:22:43.000Z","size":6346,"stargazers_count":131,"open_issues_count":1,"forks_count":10,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-22T20:31:17.165Z","etag":null,"topics":["agent","ai","ai-agent","cli","surfer-h","task-automation","vlm","web-agent","web-automation"],"latest_commit_sha":null,"homepage":"https://www.hcompany.ai/surfer-h","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hcompai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-08T09:24:53.000Z","updated_at":"2025-09-22T18:22:47.000Z","dependencies_parsed_at":"2025-07-08T09:49:52.406Z","dependency_job_id":"a74ff933-1ac3-4e90-947f-e51cfbe6c61d","html_url":"https://github.com/hcompai/surfer-h-cli","commit_stats":null,"previous_names":["hcompai/surfer-h-cli"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hcompai/surfer-h-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hcompai%2Fsurfer-h-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hcompai%2Fsurfer-h-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hcompai%2Fsurfer-h-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hcompai%2Fsurfer-h-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hcompai","download_url":"https://codeload.github.com/hcompai/surfer-h-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hcompai%2Fsurfer-h-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33092589,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-16T04:41:52.686Z","status":"ssl_error","status_checked_at":"2026-05-16T04:41:52.009Z","response_time":115,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","ai-agent","cli","surfer-h","task-automation","vlm","web-agent","web-automation"],"created_at":"2026-05-16T06:29:30.151Z","updated_at":"2026-05-16T06:29:30.805Z","avatar_url":"https://github.com/hcompai.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\n\n# Surfer-H-CLI / Open Surfer-H\n\n\n[🌐 Website](https://www.hcompany.ai/surfer-h) |\n[📖 Tech report](https://arxiv.org/abs/2506.02865) |\n[🤗 Hugging-Face Models](https://huggingface.co/collections/Hcompany) |\n[🏄 Surfer-H product](https://www.surferh.com/) |\n[☁️ AWS Model Deployment](https://aws.amazon.com/marketplace/seller-profile?id=seller-sjve6dep3p3xc)\n\n\n\u003cdiv align=\"center\"\u003e\n\n**Introducing the latest range of Holo models: [Holo1.5](https://huggingface.co/collections/Hcompany/holo15-68c1a5736e8583a309d23d9b)**\n*State-of-the-art Foundational Models for Computer Use Agents*\n\n\u003c/div\u003e\n\n## Introduction\n\nThe 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.\n\nThe 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.\n\n\n## Quick Start\n\nTo get started, first generate an API key at: https://portal.hcompany.ai.\n*This API key will allow you to run inference on H company models. Guide: [generate an API key](https://hub.hcompany.ai/surferh/generateanapikey)*\n\n\nNext, copy the example env variables.\n\n```bash\ncp .env.example .env\n```\n\nEnter your newly generated HAI_API_KEY in your .env\n\nOr setup globally: Add these to your `.zshrc` or `.bashrc` files:\n```\nexport HAI_API_KEY=...\nexport HAI_MODEL_URL=...\nexport HAI_MODEL_NAME=...\n```\n\n\nRunning via the CLI:\n```bash\n./run-on-holo.sh\n```\n\nRunning with holo1.5 as localizer (best performance):\n```bash\n./run-on-holo-1-5.sh\n```\n\nRunning with the frontend interface:\n\n```bash\n./launch.sh\n```\n\nThis command will automatically start both the Surfer-H backend and the Next.js frontend, making the web interface available at [http://localhost:3000](http://localhost:3000).\n\n\n\n# Holo models\n\n[Holo1](https://huggingface.co/collections/Hcompany/holo1-683dd1eece7eb077b96d0cbd) and [Holo1.5](https://huggingface.co/collections/Hcompany/holo15-68c1a5736e8583a309d23d9bd) are Action Vision-Language Models (VLMs) developed by [**H Company**](https://www.hcompany.ai/) 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:\n\n- **Policy**: Determines what action should be taken.\n- **Localizer**: Locates elements on the screen—like buttons, text fields, or key UI attributes.\n- **Validator**: Decides whether it succeeded or failed in doing what it set out to do.\n\nTrained 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:\n\n| Model                                                     | General purpose                                        | Inference Model Name |\n| --------------------------------------------------------- | ------------------------------------------------------ | -------------------- |\n| [Holo1 3B](https://huggingface.co/Hcompany/Holo1-3B)     | Optimized for efficiency, running locally, and hardware | holo1-3b-20250521    |\n| [Holo1 7B](https://huggingface.co/Hcompany/Holo1-7B)     | Higher accuracy and for large scale inference          | holo1-7b-20250521    |\n| [Holo1.5 3B](https://huggingface.co/Hcompany/Holo1.5-3B) | Enhanced efficiency with improved UI understanding     | holo1-5-3b-20250915  |\n| [Holo1.5 7B](https://huggingface.co/Hcompany/Holo1.5-7B) | State-of-the-art accuracy with advanced reasoning     | holo1-5-7b-20250915  |\n\n\u003e **Note:** Use the **Inference Model Name** from the table above as the value for the `HAI_MODEL_NAME` environment variable when running the agent.\n\n\n## Frontend Interface\n\nIn 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:\n\n### Features\n\n- **Task Creation**: Simply describe what you want to accomplish in natural language through a web interface\n- **Real-time Monitoring**: Watch your agent complete tasks with live updates\n- **Trajectory Management**: View, replay, and manage automated browsing sequences\n- **Settings Configuration**: Easily customize agent behavior, target URLs, and execution parameters through a UI\n- **Example Tasks**: Get started quickly with pre-configured example prompts\n\n### Interface Preview\n\n![Surfer-H Web Interface](frontend/interface-screenshot.png)\n\n*The Surfer-H web interface showing real-time agent monitoring as it searches for a beef Wellington recipe*\n\nFor detailed setup instructions, manual installation, and development information, see the [Frontend README](frontend/README.md).\n\n## View a sample run\nThe 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.`\n\u003cp align=\"center\"\u003e \u003ca href=\"https://www.youtube.com/watch?v=8PF9f3QPeO8\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e \u003cimg src=\"https://img.youtube.com/vi/8PF9f3QPeO8/0.jpg\" alt=\"Watch demo on YouTube\" /\u003e \u003c/a\u003e \u003c/p\u003e\n\n\n## Other deployment methods\n\nThere are different methods and contexts in which to deploy Holo models, including:\n\n| Method                                                                                             | Pre-requisites                                | Notes                                                                                      |\n| -------------------------------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------ |\n| [Local vLLM setup](src/surfer_h_cli/holo1/README.md)             | Install vLLM / Machine with GPU           | Uses the vLLM to download Holo1 from HuggingFace.                                                  |\n| [Local Docker Container](https://github.com/hcompai/hai-cookbook/tree/main/holo1/vllm)             | Install Docker / Machine with GPU              | Uses the `vllm/vllm-openai:v0.9.1` image.                                                  |\n| [Amazon SageMaker](https://github.com/hcompai/hai-cookbook/blob/main/holo1/sagemaker/deploy.ipynb) | Subscribe to Holo1 Models on AWS Marketplace | Deploys the Holo1 model via a prebuilt Notebook. No manual or complicated setup required. |\n\n## Run the agent locally\n\nIf you're serving your own model using vLLM, start the server with:\n\n```bash\nexport HAI_API_KEY=EMPTY\nexport HAI_MODEL_URL=http://localhost:8082/v1\nexport HAI_MODEL_NAME=Hcompany/Holo1-7B\nvllm serve Hcompany/Holo1-7B --port 8082\n```\n\nYou can then run the agent from the Surfer-H-CLI using the following command:\n\n```bash\n./run-on-holo.sh\n```\nHere are the different run settings that may apply based on use and context:\n\n- ```run-on-holo.sh``` : Use a Holo mode for navigation and localization, hosted remotely.\n- ```run-on-holo-local.sh``` : Script with specific instruction for using one or several locally hosted Holo1.\n- ```run-on-holo-val-gpt41.sh``` : Use remotely-hosted Holo model and GPT-4.1 for validation.\n\nWhen 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.\n\n\nThe above scripts call the agent like this, with different configurations for the placeholders:\n\n```bash\nMODEL=\"\u003cmodel name for endpoint\u003e\"\nTASK=\"Find a beef Wellington recipe with a rating of 4.7 or higher and at least 200 reviews.\"\nURL=\"https://www.allrecipes.com\"\n\nuv run src/surfer_h_cli/surferh.py \\\n    --task \"$TASK\" \\\n    --url \"$URL\" \\\n    --max_n_steps 30 \\\n    --base_url_localization https://\u003copenai-api-compatible-endpoint-such-as-vllm\u003e \\\n    --model_name_localization $MODEL \\\n    --temperature_localization 0.0 \\\n    --base_url_navigation https://\u003copenai-api-compatible-endpoint-such-as-vllm\u003e \\\n    --model_name_navigation $MODEL \\\n    --temperature_navigation 0.7 \\\n\n```\n### Using GPT for Validation\nTo run ```run-on-holo-val-gpt41.sh```, remember to export your OpenAI API key for validation:\n```\nexport API_KEY_VALIDATION=${OPENAI_API_KEY}\n```\nand define the correct base URL\n```\n--base_url_validation https://api.openai.com/v1/\n```\n\nFor more information, check out the [H.AI Cookbook](https://github.com/hcompai/hai-cookbook).\n\n## Citation\n\n**BibTeX:**\n\n```\n@misc{andreux2025surferhmeetsholo1costefficient,\n      title={Surfer-H Meets Holo1: Cost-Efficient Web Agent Powered by Open Weights},\n      author={Mathieu Andreux and Breno Baldas Skuk and Hamza Benchekroun and Emilien Biré and Antoine Bonnet and Riaz Bordie and Matthias Brunel and Pierre-Louis Cedoz and Antoine Chassang and Mickaël Chen and Alexandra D. Constantinou and Antoine d'Andigné and Hubert de La Jonquière and Aurélien Delfosse and Ludovic Denoyer and Alexis Deprez and Augustin Derupti and Michael Eickenberg and Mathïs Federico and Charles Kantor and Xavier Koegler and Yann Labbé and Matthew C. H. Lee and Erwan Le Jumeau de Kergaradec and Amir Mahla and Avshalom Manevich and Adrien Maret and Charles Masson and Rafaël Maurin and Arturo Mena and Philippe Modard and Axel Moyal and Axel Nguyen Kerbel and Julien Revelle and Mats L. Richter and María Santos and Laurent Sifre and Maxime Theillard and Marc Thibault and Louis Thiry and Léo Tronchon and Nicolas Usunier and Tony Wu},\n      year={2025},\n      eprint={2506.02865},\n      archivePrefix={arXiv},\n      primaryClass={cs.AI},\n      url={https://arxiv.org/abs/2506.02865},\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhcompai%2Fsurfer-h-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhcompai%2Fsurfer-h-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhcompai%2Fsurfer-h-cli/lists"}