For local runtime builders
Use this page when your local automation runtime is actively driving a browser, editor, terminal, uploader, or other app and you need Aion to treat that app as in-use instead of ordinary idle background clutter.
AI Integration Notes
Local automation runtime integration
This guide collects practical integration advice for keeping Aion from auto-closing an app while your local automation runtime is still actively driving it.
Supplemental guide, not core protocolAny local runtimeProtect apps in use
When to use it
A practical guide next to the base integration page
Keep the main AI Integration page as your baseline. Use this page when you already understand the base integration flow and now need a more workable setup for apps that are actively owned by a local automation runtime.
Keep the base guide focused
The stable socket integration guide still lives on the main AI Integration page. This page adds practical runtime guidance on top of that guide without turning every validated example into a compatibility promise.
Symptoms
These usually mean the runtime setup needs to be more robust
The app exits soon after launch
The app opens under automation, then disappears before the real task flow can settle.
Manual use works, automation does not
The same app and task work in normal user operation, but fail only when the local runtime is driving them.
Long tasks get interrupted
A long import, sync, upload, or app-driven workflow begins correctly but does not stay protected long enough to finish.
Recommended approach
Real app first, lease second
- Prefer one owned app session when possible.
- Create the real app surface before asking Aion for a lease.
- Use the most specific valid app key you can resolve for the target app instance.
- If recognition gaps are temporary, retry `lease.begin` briefly instead of immediately reworking the integration.
- Renew the lease in the background while real work is still in progress.
- Answer close checks according to whether the app is still actively owned by the runtime.
- End the lease explicitly once the task is truly complete.
App identity
How to think about `appKey`
- For many apps, the basic `appKey` is just the bundle identifier.
- Profile-aware or variant-aware apps may need a more specific suffixed key.
- Use the most specific known-valid key first, then fall back only when necessary.
Boundary
What stays stable
- The socket path, handshake flow, and lease actions still come from the main AI Integration page.
- This page adds practical runtime guidance, not a second public interface.
- Different app surfaces may need different launch, identity, and live-work checks, while still sharing the same lease flow.
Minimal shape
Protect the timing before the abstraction
The important point is not the syntax. It is the order: real app surface first, lease acquisition second, explicit cleanup at the end.
resource = launch_or_attach_to_real_app(...)
liveSurface = create_real_surface(resource)
with aion_lease(appKey):
# do the owned app work here
...
Examples
Concrete validation examples
Playwright + Chrome
One concrete validation example is Playwright driving Chrome on macOS. In that case, the more reliable approach was: create a real page first, prefer the profile-derived Chrome key, and keep the lease renewed while the browser owns live work.
Other app surfaces
If your runtime is driving some other app surface, keep the public lease flow unchanged and adapt only the app-launch, app-identity, and live-work detection layers.
Troubleshooting
Check these before changing the integration itself
`unknown_app` during `lease.begin`
Check the app key first. The best key is usually the most specific valid identity for the real app instance you just launched, not the loosest fallback.
The app exits before Aion recognizes it
Check the ordering first: real app surface first, lease second. In many integrations, that ordering matters more than later retries.
Long tasks stop halfway through
Make sure renewals continue in the background and that close checks extend the lease while the app is still actively in use.
Need the base integration page first?
If you still need the socket path, handshake, action list, or response codes, start with the main AI Integration page. Come back here when the base integration flow is clear and the remaining problem is how your runtime should own an app safely.