> ## 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.

# Migration Guide

# Migrating Agdi to a New Machine

This guide moves an Agdi gateway to a new machine without redoing onboarding.

## What Gets Migrated

When you copy the **state directory** (`~/.agdi/` by default) and your **workspace**, you preserve:

* **Config** -- `agdi.json` and all gateway settings
* **Auth** -- API keys, OAuth tokens, credential profiles
* **Sessions** -- conversation history and agent state
* **Channel state** -- WhatsApp login, Telegram session, etc.
* **Workspace files** -- `MEMORY.md`, `USER.md`, skills, and prompts

> [!TIP]
>
> Run `agdi status` on the old machine to confirm your state directory path.
> Custom profiles use `~/.agdi-<profile>/` or a path set via `OPENCLAW_STATE_DIR`.

## Migration Steps

**1. Stop the gateway and back up**

On the **old** machine, stop the gateway so files are not changing mid-copy, then archive:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi gateway stop
cd ~
tar -czf agdi-state.tgz .agdi
```

If you use multiple profiles (e.g. `~/.agdi-work`), archive each separately.

**2. Install Agdi on the new machine**

[Install](https://agdiai-597e782f.mintlify.site/install.md) the CLI (and Node if needed) on the new machine.
It is fine if onboarding creates a fresh `~/.agdi/` -- you will overwrite it next.

**3. Copy state directory and workspace**

Transfer the archive via `scp`, `rsync -a`, or an external drive, then extract:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
cd ~
tar -xzf agdi-state.tgz
```

Ensure hidden directories were included and file ownership matches the user that will run the gateway.

**4. Run doctor and verify**

On the new machine, run [Doctor](https://agdiai-597e782f.mintlify.site/gateway/doctor.md) to apply config migrations and repair services:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi doctor
agdi gateway restart
agdi status
```

## Common Pitfalls

> [accordion] Profile or state-dir mismatch
>
> If the old gateway used `--profile` or `OPENCLAW_STATE_DIR` and the new one does not,
> channels will appear logged out and sessions will be empty.
> Launch the gateway with the **same** profile or state-dir you migrated, then rerun `agdi doctor`.

> [accordion] Copying only agdi.json
>
> The config file alone is not enough. Credentials live under `credentials/`, and agent
> state lives under `agents/`. Always migrate the **entire** state directory.

> [accordion] Permissions and ownership
>
> If you copied as root or switched users, the gateway may fail to read credentials.
> Ensure the state directory and workspace are owned by the user running the gateway.

> [accordion] Remote mode
>
> If your UI points at a **remote** gateway, the remote host owns sessions and workspace.
> Migrate the gateway host itself, not your local laptop. See [FAQ](https://agdiai-597e782f.mintlify.site/help/faq.md#where-does-agdi-store-its-data).

> [accordion] Secrets in backups
>
> The state directory contains API keys, OAuth tokens, and channel credentials.
> Store backups encrypted, avoid insecure transfer channels, and rotate keys if you suspect exposure.

## Verification Checklist

On the new machine, confirm:

* [ ] `agdi status` shows the gateway running
* [ ] Channels are still connected (no re-pairing needed)
* [ ] The dashboard opens and shows existing sessions
* [ ] Workspace files (memory, configs) are present


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