> ## Documentation Index
> Fetch the complete documentation index at: https://agdiai-597e782f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup

# Setup

> [!NOTE]
>
> If you are setting up for the first time, start with [Getting Started](https://agdiai-597e782f.mintlify.site/start/getting-started.md).
> For onboarding details, see [Onboarding (CLI)](https://agdiai-597e782f.mintlify.site/start/wizard.md).

## TL;DR

* **Tailoring lives outside the repo:** `~/.agdi/workspace` (workspace) + `~/.agdi/agdi.json` (config).
* **Stable workflow:** install the macOS app; let it run the bundled Gateway.
* **Bleeding edge workflow:** run the Gateway yourself via `pnpm gateway:watch`, then let the macOS app attach in Local mode.

## Prereqs (from source)

* Node 24 recommended (Node 22 LTS, currently `22.14+`, still supported)
* `pnpm`
* Docker (optional; only for containerized setup/e2e — see [Docker](https://agdiai-597e782f.mintlify.site/install/docker.md))

## Tailoring strategy (so updates do not hurt)

If you want “100% tailored to me” *and* easy updates, keep your customization in:

* **Config:** `~/.agdi/agdi.json` (JSON/JSON5-ish)
* **Workspace:** `~/.agdi/workspace` (skills, prompts, memories; make it a private git repo)

Bootstrap once:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi setup
```

From inside this repo, use the local CLI entry:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi setup
```

If you don’t have a global install yet, run it via `pnpm agdi setup`.

## Run the Gateway from this repo

After `pnpm build`, you can run the packaged CLI directly:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
node agdi.mjs gateway --port 18789 --verbose
```

## Stable workflow (macOS app first)

1. Install + launch **Agdi.app** (menu bar).
2. Complete the onboarding/permissions checklist (TCC prompts).
3. Ensure Gateway is **Local** and running (the app manages it).
4. Link surfaces (example: WhatsApp):

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi channels login
```

5. Sanity check:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi health
```

If onboarding is not available in your build:

* Run `agdi setup`, then `agdi channels login`, then start the Gateway manually (`agdi gateway`).

## Bleeding edge workflow (Gateway in a terminal)

Goal: work on the TypeScript Gateway, get hot reload, keep the macOS app UI attached.

### 0) (Optional) Run the macOS app from source too

If you also want the macOS app on the bleeding edge:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
./scripts/restart-mac.sh
```

### 1) Start the dev Gateway

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm install
pnpm gateway:watch
```

`gateway:watch` runs the gateway in watch mode and reloads on relevant source,
config, and bundled-plugin metadata changes.

### 2) Point the macOS app at your running Gateway

In **Agdi.app**:

* Connection Mode: **Local**
  The app will attach to the running gateway on the configured port.

### 3) Verify

* In-app Gateway status should read **“Using existing gateway …”**
* Or via CLI:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi health
```

### Common footguns

* **Wrong port:** Gateway WS defaults to `ws://127.0.0.1:18789`; keep app + CLI on the same port.
* **Where state lives:**
  * Credentials: `~/.agdi/credentials/`
  * Sessions: `~/.agdi/agents/<agentId>/sessions/`
  * Logs: `/tmp/agdi/`

## Credential storage map

Use this when debugging auth or deciding what to back up:

* **WhatsApp**: `~/.agdi/credentials/whatsapp/<accountId>/creds.json`
* **Telegram bot token**: config/env or `channels.telegram.tokenFile` (regular file only; symlinks rejected)
* **Discord bot token**: config/env or SecretRef (env/file/exec providers)
* **Slack tokens**: config/env (`channels.slack.*`)
* **Pairing allowlists**:
  * `~/.agdi/credentials/<channel>-allowFrom.json` (default account)
  * `~/.agdi/credentials/<channel>-<accountId>-allowFrom.json` (non-default accounts)
* **Model auth profiles**: `~/.agdi/agents/<agentId>/agent/auth-profiles.json`
* **File-backed secrets payload (optional)**: `~/.agdi/secrets.json`
* **Legacy OAuth import**: `~/.agdi/credentials/oauth.json`
  More detail: [Security](https://agdiai-597e782f.mintlify.site/gateway/security.md#credential-storage-map).

## Updating (without wrecking your setup)

* Keep `~/.agdi/workspace` and `~/.agdi/` as “your stuff”; don’t put personal prompts/config into the `agdi` repo.
* Updating source: `git pull` + `pnpm install` (when lockfile changed) + keep using `pnpm gateway:watch`.

## Linux (systemd user service)

Linux installs use a systemd **user** service. By default, systemd stops user
services on logout/idle, which kills the Gateway. Onboarding attempts to enable
lingering for you (may prompt for sudo). If it’s still off, run:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
sudo loginctl enable-linger $USER
```

For always-on or multi-user servers, consider a **system** service instead of a
user service (no lingering needed). See [Gateway runbook](https://agdiai-597e782f.mintlify.site/gateway.md) for the systemd notes.

## Related docs

* [Gateway runbook](https://agdiai-597e782f.mintlify.site/gateway.md) (flags, supervision, ports)
* [Gateway configuration](https://agdiai-597e782f.mintlify.site/gateway/configuration.md) (config schema + examples)
* [Discord](https://agdiai-597e782f.mintlify.site/channels/discord.md) and [Telegram](https://agdiai-597e782f.mintlify.site/channels/telegram.md) (reply tags + replyToMode settings)
* [Agdi assistant setup](https://agdiai-597e782f.mintlify.site/start/agdi.md)
* [macOS app](https://agdiai-597e782f.mintlify.site/platforms/macos.md) (gateway lifecycle)


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