Skip to main content
The SDK does not embed ADE as a library. It spawns ade runtime run --socket <path> --profile embedded as a child.
--profile embedded is the only profile ade runtime run accepts. Anything else is a usage error, not a silent fall back to a full brain.

​
Guest rules

  • Isolated home. Never ~/.ade.
  • Sync is forced off. The sidecar is not a machine peer.
  • No machine authority. machine.updateAndRestart and power transitions are withheld, not merely role-gated.
  • Parent-death watchdog. POSIX does not kill orphans on parent death. The runtime polls ADE_EMBEDDED_PARENT_PID and shuts itself down if the host is gone.
  • Host ADE_* env is scrubbed before spawn so a developer ADE install cannot leak into the guest.

​
Pidfile reclaim

<home>/runtime.pid records the child. If a previous host died without unwinding, the next createAdeChat reclaims:
  • A healthy runtime already bound to this home is reused.
  • A confirmed-stale child is ended, then a new one is spawned.
  • A pid that cannot be corroborated (recycling, start-time mismatch, pid 0) is left alone and start fails. Spawning a second writer on the same SQLite root is worse.

​
Events

The client prefers push (personalChats.subscribeEvents). If the runtime omits that capability, it drains personalChats.streamEvents by cursor. doctor().events.mode is "push", "drain", or "unavailable".

​
doctor()

Use this as the first check when an embedder chat misbehaves. sdkVersion is this package; socket.runtimeVersion is the sidecar binary. They ship on separate cadences. See Reference for the full shape.

​
Windows

Parity is required. Named pipes, GLOBALROOT System32 tools, ComSpec for .cmd / .bat, and file-lock retries are all in the client. See Install.