Migration Guide

このコンテンツはまだ日本語訳がありません。

Migrating CoderClaw to a new machine

This guide migrates a CoderClaw Gateway from one machine to another without redoing onboarding.

The migration is simple conceptually:

Copy the state directory ($CODERCLAW_STATE_DIR, default: ~/.coderclaw/) — this includes config, auth, sessions, and channel state.
Copy your workspace (~/.coderclaw/workspace/ by default) — this includes your agent files (memory, prompts, etc.).

But there are common footguns around profiles, permissions, and partial copies.

Before you start (what you are migrating)

1) Identify your state directory

Most installs use the default:

State dir: ~/.coderclaw/

But it may be different if you use:

--profile <name> (often becomes ~/.coderclaw-<profile>/)
CODERCLAW_STATE_DIR=/some/path

If you’re not sure, run on the old machine:

coderclaw status

Look for mentions of CODERCLAW_STATE_DIR / profile in the output. If you run multiple gateways, repeat for each profile.

2) Identify your workspace

Common defaults:

~/.coderclaw/workspace/ (recommended workspace)
a custom folder you created

Your workspace is where files like MEMORY.md, USER.md, and memory/*.md live.

3) Understand what you will preserve

If you copy both the state dir and workspace, you keep:

Gateway configuration (coderclaw.json)
Auth profiles / API keys / OAuth tokens
Session history + agent state
Channel state (e.g. WhatsApp login/session)
Your workspace files (memory, skills notes, etc.)

If you copy only the workspace (e.g., via Git), you do not preserve:

sessions
credentials
channel logins

Those live under $CODERCLAW_STATE_DIR.

Migration steps (recommended)

Step 0 — Make a backup (old machine)

On the old machine, stop the gateway first so files aren’t changing mid-copy:

coderclaw gateway stop

(Optional but recommended) archive the state dir and workspace:

# Adjust paths if you use a profile or custom locations
cd ~
tar -czf coderclaw-state.tgz .coderclaw

tar -czf coderclaw-workspace.tgz .coderclaw/workspace

If you have multiple profiles/state dirs (e.g. ~/.coderclaw-main, ~/.coderclaw-work), archive each.

Step 1 — Install CoderClaw on the new machine

On the new machine, install the CLI (and Node if needed):

See: Install

At this stage, it’s OK if onboarding creates a fresh ~/.coderclaw/ — you will overwrite it in the next step.

Step 2 — Copy the state dir + workspace to the new machine

Copy both:

$CODERCLAW_STATE_DIR (default ~/.coderclaw/)
your workspace (default ~/.coderclaw/workspace/)

Common approaches:

scp the tarballs and extract
rsync -a over SSH
external drive

After copying, ensure:

Hidden directories were included (e.g. .coderclaw/)
File ownership is correct for the user running the gateway

Step 3 — Run Doctor (migrations + service repair)

On the new machine:

coderclaw doctor

Doctor is the “safe boring” command. It repairs services, applies config migrations, and warns about mismatches.

Then:

coderclaw gateway restart
coderclaw status

Common footguns (and how to avoid them)

Footgun: profile / state-dir mismatch

If you ran the old gateway with a profile (or CODERCLAW_STATE_DIR), and the new gateway uses a different one, you’ll see symptoms like:

config changes not taking effect
channels missing / logged out
empty session history

Fix: run the gateway/service using the same profile/state dir you migrated, then rerun:

coderclaw doctor

Footgun: copying only `coderclaw.json`

coderclaw.json is not enough. Many providers store state under:

$CODERCLAW_STATE_DIR/credentials/
$CODERCLAW_STATE_DIR/agents/<agentId>/...

Always migrate the entire $CODERCLAW_STATE_DIR folder.

Footgun: permissions / ownership

If you copied as root or changed users, the gateway may fail to read credentials/sessions.

Fix: ensure the state dir + workspace are owned by the user running the gateway.

Footgun: migrating between remote/local modes

If your UI (WebUI/TUI) points at a remote gateway, the remote host owns the session store + workspace.
Migrating your laptop won’t move the remote gateway’s state.

If you’re in remote mode, migrate the gateway host.

Footgun: secrets in backups

$CODERCLAW_STATE_DIR contains secrets (API keys, OAuth tokens, WhatsApp creds). Treat backups like production secrets:

store encrypted
avoid sharing over insecure channels
rotate keys if you suspect exposure

Verification checklist

On the new machine, confirm:

coderclaw status shows the gateway running
Your channels are still connected (e.g. WhatsApp doesn’t require re-pair)
The dashboard opens and shows existing sessions
Your workspace files (memory, configs) are present