> ## Documentation Index
> Fetch the complete documentation index at: https://ade-app.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Install

> Install @ade-dev/sdk and @ade-dev/chat-ui. Node 22, an isolated home directory, and how the sidecar finds an ade binary.

```bash theme={null}
npm install @ade-dev/sdk
```

Optional UI:

```bash theme={null}
npm install @ade-dev/chat-ui
```

Requires **Node 22**. The packages ship ESM + CJS.

## Isolated home

Pass a directory your app owns. The sidecar stores thread keys and runtime state there. Never point it at the developer's `~/.ade` or at ADE's default machine socket.

```ts theme={null}
import { createAdeChat } from "@ade-dev/sdk";

const ade = await createAdeChat({
  home: "./.ade-embed", // created if missing, mode 0700
});
```

In Electron, use the main process and a path under `userData`:

```ts theme={null}
import path from "node:path";
import { app } from "electron";
import { createAdeChat } from "@ade-dev/sdk";

const ade = await createAdeChat({
  home: path.join(app.getPath("userData"), "ade"),
});
```

Two clients on one `home` fight over the same socket and SQLite root. Open **one** client per isolated home.

## Where `ade` comes from

Resolution order:

1. `binaryPath` — pin a specific build; skips everything below.
2. An installed `@ade-dev/runtime-<target>` platform package.
3. A previously downloaded binary in the home cache.
4. `ade` on `PATH` (optional; tests can disable this).
5. Download from the ADE GitHub release, fail-closed against that release's `SHA256SUMS`.

```ts theme={null}
const ade = await createAdeChat({
  home: "./.ade-embed",
  binaryPath: "/usr/local/bin/ade",  // skip everything below
  runtimeNodeModules: "/opt/ade/native/node_modules", // when they are not beside the binary
  allowDownload: false,              // throw runtime_unavailable instead of fetching
  channel: "latest",                 // or a release tag
});
```

The platform package sits directly below the pinned path because installing it is itself an explicit act: it is in your lockfile and inside your bundle, and a download must never quietly take precedence over the copy you signed.

`allowDownload: false` is what a shipping app wants. A packaging mistake then fails loudly in QA rather than working through a silent download on the developer's machine and failing on a locked-down user's.

`channel: "latest"` downloads the newest runtime, which can be outside the range this SDK supports. See [Version compatibility](https://ade-app.dev/docs/sdk/runtime.md#version-compatibility).

Downloads verify checksums before the binary is used. A mismatch is a hard error (`checksum_mismatch`), not a warning. The pinned and bundled routes skip that check by design: bytes you signed into your own bundle are verified by the OS.

> [card] [Bundling](https://ade-app.dev/docs/sdk/bundling.md)
>
> Ship the runtime inside a signed app: platform packages, `codesign` lines, entitlements, electron-builder.

## Electron

Run `@ade-dev/sdk` from the **main process**, not the renderer. Spawn owns a child process and a Unix socket (or a Windows named pipe), and a sandboxed renderer has neither.

Do not write the bridge yourself. `@ade-dev/sdk/electron` ships it: one function per process, listener teardown on reload, and the history-and-live ordering rule in code.

> [card] [Electron bridge](https://ade-app.dev/docs/sdk/electron.md)
>
> `registerAdeIpc`, `exposeAdeBridge`, `createAdeIpcClient`, and what `sandbox: true` requires.

## Windows

The sidecar is a supported host. Named pipes are hashed from home + user identity. `taskkill` / `tar` are resolved through the kernel `GLOBALROOT` System32 alias, never from `PATH`. `.cmd` / `.bat` wrappers spawn through `ComSpec`.

## Next

> [card] [Quickstart](https://ade-app.dev/docs/sdk/quickstart.md)
>
> Open a thread and send the first message.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.