Add the JSON to Xcode
Drag HaloIntegration.json into your project. Enable Copy items if needed and select the macOS app target.
HALO INTEGRATION PROTOCOL · v2
Connect your app to Halo.
Actions, triggers, and delivery included.
Describe what your macOS app can do, what input each action accepts, what should activate it, and how Halo should deliver requests. The builder generates a HaloIntegration.json that matches Halo's current protocol-v2 decoder.
1App identity
→
2Actions & inputs
→
3Triggers
→
4Receive requests
MANIFEST BUILDER
App details
Actions
Each action declares its own input contract and typed options. File actions must list accepted extensions because Halo uses them for drag eligibility.
Triggers
Triggers decide when an integration becomes eligible. A fileDrag trigger must reference one or more file-input actions.
DELIVERY
openRequest
Current Halo builds deliver a temporary .halorequest plus the authorized input files through the normal macOS open-URL flow.
IMPLEMENTATION
Ship the manifest, then receive Halo actions
Discovery and invocation are separate. The manifest tells Halo what your app supports; your app still needs to receive the request and perform the declared action.
Confirm bundle resource
In Build Phases → Copy Bundle Resources, verify that HaloIntegration.json is present.
Register Halo requests
Register the .halorequest document type so macOS can deliver Halo's request envelope to your app.
Handle opened URLs
Decode the request, resolve actionID, then perform the action using the other file URLs supplied in the same open request.
Halo discovers the manifest at
YourApp.app/Contents/Resources/HaloIntegration.json
Important: A valid manifest only makes your app discoverable/configurable. If you do not implement the
.halorequest receiver, Halo can still open/send files to your app, but your app will not know which declared action Halo requested.
SWIFT
Receive Halo actions
INFO.PLIST
Register .halorequest
REFERENCE
Protocol-v2 template
SWIFT
Manifest models
CURRENT HALO CONTRACT
Schema at a glance
| Field | Type | Current behavior |
|---|---|---|
protocolVersion | Integer | Use 2 for new integrations. Halo still normalizes v1 for compatibility. |
app.name | String | Human-readable application name. |
app.bundleIdentifier | String | Must exactly match the containing macOS app bundle. |
actions[].id | Identifier | Stable action identity used for configuration and delivery. |
actions[].input.type | none | files | Declares whether the action needs selected files. |
actions[].input.extensions | String[] | Required for functional file actions. No dots; * means any extension. |
actions[].input.multiple | Boolean | When false, a multi-file drag is not eligible for that action. |
actions[].options[].default | Typed value? | Optional default must match the option's declared type. |
triggers[].type | Enum | fileDrag, keyboardShortcut, manual, or schema-valid partnerEvent. |
triggers[].actions | String[] | References stable action IDs. fileDrag may reference only file-input actions. |
triggers[].eventName | Identifier? | Required for partnerEvent. External event ingress is not active yet. |
delivery.type | String | Current supported value: openRequest. |
VALIDATION LIMITS
The builder checks the same important limits Halo enforces
256 KBmaximum manifest size
64maximum actions
32maximum options per action
32maximum triggers