Developer guide

AI Integration

Keep Aion from auto-closing an app while your local AI or agent workflow is actively using it.

Local-only integrationSame-user socket transportClose-check before auto-quit

Who this is for

A stable integration boundary, not a hidden control surface

The point of this page is to help technically capable users and local automation builders integrate with Aion without turning internal implementation details into long-term compatibility promises.

For local agent builders

Use this guide when your local agent is actively driving a browser, editor, or other app and you do not want Aion to treat that app like ordinary idle background clutter.

For ordinary Aion users

This page explains the public integration path behind Aion’s AI protection behavior. It is not required for normal use unless you are wiring your own local automation runtime.

Transport

Current public route

Public transport route

Aion exposes a same-user Unix domain socket for AI lease traffic.

~/Library/Application Support/Aion/ipc/ai-protection.sock

What is not exposed

There is no localhost HTTP server, no dedicated XPC endpoint, no custom URL scheme, and no DistributedNotification transport for this feature.

Protocol flow

What a working session looks like

  1. Connect to the socket as the same macOS user that is running Aion.
  2. Send `session.hello` with `protocolVersion: 1`, your `holderId`, a readable `clientName`, and your `pid`.
  3. Wait for `session.ready` before sending business messages.
  4. Send lease messages using the existing `AIAppLeaseEnvelope` payload shape.
  5. If Aion needs a final decision before auto-quit after lease expiry and grace, it pushes one `lease.can_close.request` to the live connection for that `holderId`.
  6. Reply with `lease.can_close.reply` to either allow close or extend the lease.

Actions

Messages you can send

  • lease.begin
  • lease.renew
  • lease.end
  • lease.can_close.reply
Aion may send back

lease.can_close.request

Handshake and transport errors

Messages before business traffic starts

  • session.hello
  • session.ready
  • session.error
invalid_handshakeunsupported_protocol_versionholder_id_mismatchunauthenticated

App identity

How `appKey` works today

  • For most apps, `appKey` is the bundle identifier, such as `com.google.Chrome`.
  • Profile-aware or variant-aware apps may use suffixed keys such as `com.google.Chrome#profile-work`.
  • Unknown app keys are rejected with `unknown_app`.

Policy limits

Current timing bounds

  • Minimum lease: 60 seconds
  • Maximum lease: 1800 seconds
  • Grace period after active lease: 60 seconds
  • Close-check timeout: 3 seconds
  • Close-check cooldown: 15 seconds

Examples

Minimal payloads

Handshake

{
  "action": "session.hello",
  "protocolVersion": 1,
  "holderId": "agent.local.test",
  "clientName": "Test Agent",
  "pid": 42
}

Begin a lease

{
  "action": "lease.begin",
  "requestId": "req_123",
  "holderId": "agent.local.test",
  "appKey": "com.google.Chrome",
  "leaseSeconds": 600
}

Reply to close-check

{
  "action": "lease.can_close.reply",
  "requestId": "close_777",
  "holderId": "agent.local.test",
  "appKey": "com.google.Chrome",
  "result": "extend_lease",
  "leaseSeconds": 300
}

Lease responses

Current response codes

acceptedinvalid_payloadunknown_actionunknown_appnot_entitledholder_mismatchrequest_expiredlease_conflict

Boundary

What stays public, and what does not

Stable public surface

  • The socket path and same-user local transport model.
  • The handshake messages: `session.hello`, `session.ready`, and `session.error`.
  • The supported lease actions and current response codes listed on this page.
  • The fact that Aion may push one `lease.can_close.request` before auto-quit proceeds after expiry and grace.

Not a compatibility promise

  • Internal store layout, actor boundaries, and UI wiring.
  • Undocumented transports or debug-only entry points.
  • A promise that every internal state change will appear as a stable public API event.

Recipes

Implementation notes for specific surfaces

Start with the stable integration surface on this page. If your integration surface has its own practical quirks, use a recipe page like the one below rather than turning the base guide into an ever-growing troubleshooting dump.

Local automation runtime integration

A practical guide for local runtimes that actively drive an app and need Aion to keep treating that app as in-use instead of ordinary idle background state.

Read the runtime guide

Need a human fallback?

If you are building a local agent integration and the current guide is not enough, email the use case and the exact message flow you need. For normal setup questions, the user guide is still the faster path.

Read the user guide [email protected]