Halo

Halo is an Electron desktop app with a React renderer and Pi in an independent Node workspace server.

Structure

• apps/electron/src/renderer: React UI built with Maui and Vite.
• apps/electron/src/main: Electron main process, preload bridge, and server connection discovery.
• apps/workspace-server: Workspace server process (@get-halo/workspace-server-app).
• packages/workspace-server: Reusable workspace server library (@get-halo/workspace-server).
• infra: GCP/Pulumi infrastructure.
• packages/halo-cli: Workspace commands and private browser testing for workspace agents.
• packages/dev-cli: Local development commands, currently Electron app control.
• packages/logger: Shared structured logger.
• packages/typescript-config: Shared TypeScript settings.

Local development

Install pnpm 12 with the standalone script, not Corepack. latest on npm still points at pnpm 11, so pass the 12 line explicitly:

curl -fsSL https://get.pnpm.io/install.sh | env PNPM_VERSION=12.1.0 sh -
pnpm install
pnpm dev

On Linux hosts without a real GPU (including Cursor cloud agents on Xvfb), set HALO_USE_SWIFTSHADER=1 before starting Halo. The Cursor environment terminal always exports it.

export HALO_USE_SWIFTSHADER=1
pnpm dev

Halo reads model and authentication credentials from GCP Secret Manager at runtime using Application Default Credentials. Follow the infrastructure secret setup before starting development.

In Electron development mode, Halo also derives its local UI identity from the active ADC principal. User ADC appears as that Google user; service-account ADC appears as the service account email. This skips browser Google sign-in only for the local Electron app. Packaged builds and the browser app continue to use Better Auth with Google sign-in.

pnpm dev starts the control plane, workspace server, web app, and Electron independently, using <repo>/tmp/workspace and <repo>/tmp/workspace/.halo. Electron discovers the server through server.json in that application-data directory; closing Electron leaves the server running. When launching services individually, use HALO_WORKSPACE_ROOT to select the workspace and HALO_USER_DATA to select the application-data directory. See workspace-server configuration.

Halo runs Pi's AgentHarness with one main lane per conversation. HaloServer owns a DatabaseClient that stores Pi conversations and Executor application data in one embedded Turso database. The file currently lives in the selected workspace:

<workspace>/
└── .halo/
    └── state.db

Halo's TursoThreadRepo owns thread metadata in halo_threads, and TursoStorage implements Pi's durable storage contract. Pi owns conversations, entries, tasks, submissions, and documents within each thread.

WorkspaceServer constructs the thread repository and supplies database access to ToolRuntime. Both reads and writes wait for admitted transactions, so neither consumer can observe the other's uncommitted changes. Transaction callbacks must use their supplied connection/query and must not wait for tools, network calls, or model inference.

The adapter uses Turso's synchronous compatibility driver and ordinary tables. Turso 0.7.2 does not support recursive CTEs, so branch scans follow indexed parent links without a separate branch-index table. The schema is bundled with Halo; there is no Pi SQLite backend dependency, package patch, or SQL asset-copy step. Existing JSONL and vendor SQLite tables are not imported.

Shutdown stops HTTP admission, closes threads, drains request handlers, stops tools, closes the repository, then closes the database. Executor retains its generated table/index names and independent schema version. Future Halo and extension tables must avoid existing names; use halo_* and ext_<installation>_*. Extensions are trusted, so Halo does not store extension grants. Extension records and the credential vault have not moved into this database yet.

The renderer consumes Halo thread snapshots and events, adapted from Pi at the server boundary. The thread protocol describes stable entries, run state, and first-class nested exec activity. It uses Pi's supplied transcript; loading older entries before compaction is deferred. client.thread.events sends an initial snapshot followed by ephemeral live events; disconnecting a viewer leaves its running thread active. Nested exec tool details persist in Pi's tool results and progress checkpoints. Halo does not keep a separate event log or import existing JSONL conversation files.

Pi's file and shell tools run on the host with the same rights as Halo. Halo does not import old AgentOS SQLite workspaces.

The workspace server reads required credentials from GCP Secret Manager. It does not pass them through renderer IPC or extension process environments.

Debug UI control

Development builds expose Electron's Chrome DevTools Protocol on 127.0.0.1:4445. The separate pnpm halo-dev command uses Electron's local app-control connection to attach with Libretto Browser Tools and leaves Halo running. Electron owns this endpoint; the workspace server does not. For the root dev stack:

pnpm halo status
pnpm halo-dev app snapshot
pnpm halo-dev app exec "return await page.locator('body').innerText()"
pnpm halo-dev app exec "await page.getByRole('button', { name: 'New thread' }).click()"

Agents drive the workspace's own Chrome from exec with tools.browser, a Playwright-style client: const page = await tools.browser.newPage({ url }), then page.getByRole(...).click(). Each action is one browser.call tool call, which runs one Playwright page or locator method on a tab named by its Chrome target ID.

For halo-dev app exec, pass --stdin or --file checks.js for longer scripts. Output uses TOON by default; pass --json for JSON. Packaged builds do not expose the debug port.

Infrastructure

Infrastructure targets GCP project halo-relay with Pulumi. See the infrastructure instructions for bootstrapping, previewing, and deploying the production control plane and workspace images.

Packaging

pnpm --filter @get-halo/desktop build
pnpm --filter @get-halo/desktop make

Electron Forge writes packaged apps to apps/electron/out.

Releasing

Halo uses one release PR for its infrastructure, cloud services, workspace VMs, and desktop application. From a clean, up-to-date main branch, run:

pnpm prerelease 0.1.44

The command creates release/0.1.44, bumps the desktop and production image versions, adds releases/0.1.44.json, pushes the branch, and opens the PR.

The PR runs the normal repository checks, all package E2Es (including packaged macOS tests), and the production Pulumi preview. Release ready requires the E2Es and preview to pass before merge. E2Es run without Turbo cache reuse and without affected-package filtering, so a version-only PR still tests the full release. Merging it runs Release Halo in this order, without rerunning E2Es:

1. Build versioned control-plane and workspace images.
2. Apply the production Pulumi stack.
3. Check the control-plane health endpoint.
4. Recreate each workspace VM while preserving its durable data disk.
5. Create the matching tag and GitHub Release.
6. Build, sign, notarize, and publish the desktop application.

Packaged macOS and Windows builds check for updates through update.electronjs.org, which reads those GitHub Releases. macOS builds are signed and notarized in CI.

One-time GitHub setup

Create a GitHub Environment named Release (name is case-sensitive) and add:

Variables

• APPLE_TEAM_ID — Apple Team ID (for example S2ZR72G4R4)

Secrets

• APPLE_CERTIFICATE_BASE64 — base64-encoded Developer ID Application .p12
• APPLE_CERTIFICATE_PASSWORD — password for that .p12
• APPLE_API_KEY_BASE64 — base64-encoded App Store Connect API .p8 key
• APPLE_API_KEY_ID — App Store Connect API key id
• APPLE_API_ISSUER — App Store Connect issuer UUID

Do not add required reviewers to the Release environment. Reviewing and merging the release PR is the production approval.

Configure GitHub Actions to authenticate to GCP through Workload Identity Federation, then add these repository variables:

• GCP_WORKLOAD_IDENTITY_PROVIDER — full Workload Identity provider resource name.
• GCP_DEPLOY_SERVICE_ACCOUNT — deployment service account email.

The identity needs access to the Pulumi state bucket and KMS key, permission to submit the existing Cloud Build configurations, and the GCP permissions required by the production Pulumi stack. Require PR review and Check / check-affected plus Release Halo / Release ready through the main branch ruleset. The second check is lightweight for ordinary PRs and requires successful E2Es and a Pulumi preview for release PRs. For security, release PRs must use a release/* branch in this repository; forks cannot access the production preview identity.

Checks

Pull requests and pushes to main run pnpm run check-affected on GitHub Actions (Check / check-affected). This runs lint, typechecking, formatting checks, and unit tests for affected packages. It does not run E2Es or package Electron.

pnpm run check-affected

Run E2Es for affected packages separately:

pnpm run test:e2e

For a focused run, use the package's test:e2e command. Desktop E2Es also offer test:e2e:build and test:e2e:run <test-file> --workers=1 to reuse a build and limit CPU usage. CI runs E2Es only on release PRs, using pnpm run test:e2e:release to run every package suite, including packaged Electron. Ordinary PRs and post-merge release jobs do not run E2Es.

Tests do not call a paid model.

License

Copyright 2026 Saffron Health, Inc.

Halo is licensed under the Apache License, Version 2.0. See NOTICE for attribution. Third-party code and dependencies retain their respective licenses, including the MIT-licensed tool in tools/oxlint/anti-slop/.