For local runtime builders
Use this when your local automation tool is driving a browser, editor, terminal, uploader, or other app and Aion should treat that app as busy until the task finishes.
Automation integration notes
Local automation runtime integration
This guide explains how to keep Aion from closing an app while your local automation tool is still using it.
Practical setup notesFor local automation toolsKeep active apps open
When to use it
A practical guide next to the base integration page
Keep the main integration page as your baseline. Use this page when the base flow is clear and the remaining problem is how your tool should keep a real app protected while it works.
Keep the base guide focused
The stable socket guide still lives on the main integration page. This page adds setup advice for real local runtimes and concrete app-launch behavior.
Symptoms
These signs usually mean the setup needs one more rule
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
Open the real app first, then ask for protection
- 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 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 main integration page first?
If you still need the socket path, handshake, action list, or response codes, start with the main integration page. Come back here when the base flow is clear and you are tuning a specific runtime.