DOCSEARCHbyAlgolia
Submit Docs

Halo AI Workstation Documentation

repository·main·Indexed 23 days ago

https://github.com/openkursar/hello-halo

Halo is an AI workstation for automating complex workflows using autonomous 'AI Digital Humans' and reliable 'Browser Actions' via a pluggable engine architecture. It features 100% local execution for privacy, remote management via WeChat/WeCom, and a desktop architecture combining a React UI with a Main Process and Claude Code SDK. The documentation covers developing from source, implementing custom AI Source Providers (API key and OAuth), performance monitoring, and Capacitor configurations for mobile deployment.

Tokens
68.7K
Snippets
110
Records
342
Agent score
81%

What's inside Halo

  1. What is Halo and how does it work?

    main

    Halo is an AI workstation designed for teams and individuals that can be deployed locally. It features a pluggable engine architecture compatible with agents like Claude Code and Codex.

    Key capabilities include:

    • 100% Local: Data stays on your machine, meeting enterprise compliance requirements.
    • AI Digital Humans: Autonomous agents that run 24/7 to handle monitoring, reporting, and routine tasks.
    • AI Browser: An integrated browser controlled by AI to automate web-based systems.
    • Remote Access: Control your AI fleet from mobile devices (Smartphone/H5/WeChat/Android).
    • Enterprise Integration: Native control via WeCom/WeChat for managing and training agents through IM.

  2. Overview of Halo AI Workstation

    main

    Halo is a local AI workstation designed for individuals and teams. It features a pluggable engine architecture compatible with Claude Code, Codex, and other agents.

    Key features include:

    • 100% Local Execution: Data remains on your machine for enterprise compliance.
    • AI Digital Humans: Autonomous AI workers that run 24/7 to manage monitoring, reporting, and routine operations.
    • AI Browser: An integrated browser controlled by AI to automate web-based systems.
    • Remote Access: Manage your AI fleet via mobile (H5, WeChat, Android).
    • Native WeCom/WeChat Control: Manage agents directly through enterprise IM.
    • Artifact Rail: A UI component where generated files appear for preview and modification.

  3. Use CapApp-SPM to host SPM dependencies

    main

    The CapApp-SPM package is a dedicated container used to host Swift Package Manager (SPM) dependencies for Capacitor projects.

    Warning: Do not modify the contents of this package, as doing so may cause unintended consequences in the dependency resolution or the build process of your Capacitor application.

  4. Enterprise Deployment Overview

    main

    Halo supports enterprise customization through a product.json configuration and an electron-builder overlay. This allows IT and R&D teams to distribute a branded version of Halo (e.g., with company logos, internal AI gateways, and SSO) without modifying the upstream hello-halo repository. This architecture ensures that the main repository remains clean and easy to upgrade.

    Deployment Structure

    Customizations are organized in a three-tier hierarchy:

    1. hello-halo/: The main upstream repository (unchanged).
    2. halo-local/: A private workspace (independent git repository) located within the main repo.
    3. halo-local/<company_name>/: The enterprise overlay (independent git repository) containing specific configurations.

    Common Customization Areas

    • Branding: App name, Bundle ID, icons, data directory, and version info.
    • AI Integration: Pre-configuring internal AI gateway addresses (OpenAI/Anthropic compatible).
    • Authentication: Integrating company SSO/OAuth or pre-set API keys.
    • Security: Disabling Cloudflare Tunnels, restricting remote MCP installation, encrypting credentials with SM4, and setting browser domain allowlists.
    • Updates: Pointing automatic updates to internal static servers or artifact repositories.

  5. Core features of Halo

    main

    Halo is an AI workstation designed for autonomous agent workflows. Key features include:

    • 100% Local: Data remains on your machine to meet enterprise compliance requirements.
    • Backend-less: A pure desktop client that deploys to workstations without requiring server infrastructure.
    • Agent Loop: Supports not just text generation, but actual tool execution.
    • Space System: Isolated workspaces to prevent interference between different projects.
    • Skills: Extend agent capabilities by installing Skill packs.
    • AI Browser: Includes a built-in CDP browser that allows the AI to directly control web pages.
    • Multi-model Support: Compatible with Anthropic, OpenAI, DeepSeek, and all OpenAI-compatible APIs (including enterprise LLM gateways).
    • Remote Access: Manage your AI fleet from anywhere.

  6. Key Features of Halo

    main

    Halo provides several core capabilities for AI-driven workflows:

    • 100% Local: Data remains on your machine for enterprise compliance.
    • No Backend Required: Operates as a pure desktop client without needing server infrastructure.
    • Agent Loop: Supports actual tool execution rather than just text generation.
    • Space System: Provides isolated workspaces so projects do not interfere with each other.
    • Skills: Extensible capability via skill packages.
    • AI Browser: An embedded CDP-based browser that allows the AI to control web pages directly.
    • Multi-Model Support: Compatible with Anthropic, OpenAI, DeepSeek, and any OpenAI-compatible API (including enterprise LLM gateways).
    • Remote Access: Ability to manage your AI fleet from anywhere.

  7. Explore the App Runtime module structure

    main

    The apps/runtime module is organized into several functional areas:

    Core Runtime

    • service.ts: Implementation of AppRuntimeService.
    • execute.ts: Core logic for executeRun() automation runs.
    • store.ts: ActivityStore for CRUD operations on runs and entries.
    • concurrency.ts: Implements a counting semaphore for concurrency control.
    • prompt.ts: Builds system prompts for headless automation sessions.
    • report-tool.ts & notify-tool.ts: SDK MCP tools for user reporting and notifications.

    Interactive Chat & IM Integration

    • app-chat.ts: Manages sendAppChatMessage() and chat session lifecycles.
    • im-channels/: Manages IM channel lifecycles and provider-specific implementations (e.g., wecom-bot.provider.ts).
    • im-session-registry.ts: Manages persistent IM sessions per app, channel, and chatId.
    • file-export-gate.ts: Handles the filesystem boundary for AI-attached files.

    Prompt Engineering

    • prompt/: Contains logic for assembling chat prompts, including identity fragments (identity.ts), capability guidance (capabilities.ts), and native UI entry fragments (entry-native.ts).

  8. Overview of the AI Terminal service

    main

    The ai-terminal is a pty-backed terminal subsystem that allows an AI to drive interactive terminal sessions via MCP tools while providing a live xterm.js view for human users.

    Key Characteristics:

    • Full-Duplex Control: Users can watch the AI work in the Canvas and take over the same pty at any time. Ctrl+C always reaches the pty.
    • Process-Scoped Sessions: Pty sessions are decoupled from SDK sessions or UI windows. A task continues running even if the model switches, the session rebuilds, or the canvas is closed.
    • Platform Support: Available on macOS and Windows only. Linux is explicitly excluded (the feature is gated via isTerminalAvailable()).

  9. Use AI Digital Humans for autonomous tasks

    main

    AI Digital Humans are autonomous agents that run 24/7 based on a task and a frequency. They combine the capabilities of a cron job, RPA, and an AI Agent.

    Key features include:

    • Autonomous Execution: They follow a schedule to perform tasks without manual intervention.
    • Control via IM: You can manage and command Digital Humans directly through WeChat or Enterprise WeChat (WeCom) to check progress or issue new instructions.
    • Deployment: You can install ready-made Digital Humans from the AI Digital Human Store or create your own using natural language.

    Common use cases include social media automation (replying to comments, posting content), enterprise automation (monitoring CRM/ERP, generating reports from Jira/GitHub), and DevOps monitoring.

  10. Understand AI Browser view lifecycle events

    main

    The interactive singleton context broadcasts view lifecycle events to a process-global bus. The transport module (ipc/ai-browser.ts) subscribes to these and fans them out to the BrowserWindow and remote WebSocket clients.

    EventChannelMeaningRenderer effect
    active-viewai-browser:active-view-changedAI created/selected a viewAttaches the live feed to the UI via activeViewId.
    goneai-browser:view-goneAI's active view destroyedClears the store and drops the live-session tray.

  11. Localize App UI with `i18n`

    main

    The i18n block provides locale-specific overrides for display text in the App Store and installation forms.

    Important Constraints:

    • Only display text is translated. system_prompt, store metadata, subscription config, and runtime behavior are never overridden by i18n.
    • The top-level name, description, and config_schema are the authoritative English sources.
    • Locale Resolution Order:
      1. Exact locale match (e.g., zh-CN).
      2. Language-prefix match (e.g., zh-TW falls back to zh-CN).
      3. Canonical fallback (English).

    Structure:

    • I18nLocaleBlock: Contains name, description, and config_schema (a map of overrides).
    • I18nConfigFieldOverride: Contains label, description, placeholder, and options (a map of value $\rightarrow$ translated label).
    i18n:
  zh-CN:
    name: 京东价格猎手
    description: 监控京东商品页面的价格变动...
    config_schema:
      product_url:
        label: 商品链接
        description: 京东商品详情页链接
        placeholder: "https://item.jd.com/..."
      target_price:
        label: 目标价格
      output_language:
        label: 输出语言
        options:
          en-US: 英文
          zh-CN: 中文

  12. Understand the App Manager module role

    main

    The apps/manager module serves as a pure data and persistence layer for managing the lifecycle of Apps.

    Key responsibilities:

    • Managing App lifecycle states and persistence.
    • Providing data to apps/runtime (for activation and status updates) and the renderer (via IPC for UI).

    What it does NOT do:

    • It does not execute Apps.
    • It does not trigger scheduling.
    • It does not call Agents.