Rebuild a Server for Claude Code: Backups & Next Steps
When you rebuild a server that runs Claude Code, you need to back up your Claude Code configuration, project state, and any custom scripts or MCP settings, then reinstall the CLI, restore those files, and re-authenticate. This article walks you through exactly what to save before you wipe the machine and the order of operations to get back to work quickly.
What Actually Lives on the Server
Claude Code stores its state in a few places. The most important are your authentication credentials, your settings file, and any project-level configuration. If you skip these, you will have to re-login and reconfigure everything from scratch.
- Authentication: Your login session is cached in
~/.claude/(or the equivalent user config directory on your OS). Copy the whole folder to be safe. - Settings: The main config file is usually
settings.jsoninside that same.claudedirectory. It holds your model preferences, permissions, and custom instructions. - Project state: Claude Code keeps conversation history and session data in a local database or JSON files, often under
.claude/inside each project folder. If you want to resume old conversations, back these up too. - MCP servers: If you use Model Context Protocol servers, their configuration is in your settings file or in a separate
.mcp.jsonat the project root. - Custom scripts and hooks: Any shell scripts, plugins, or hooks you’ve written should be copied to your backup, especially if they live outside the project directory.
Step-by-Step Backup Checklist
Before you tear down the old server, run through this list. It takes about five minutes and saves you an afternoon of reconfiguration.
- Find the config directory: run
echo $HOME/.claudeon Linux/macOS, or check%USERPROFILE%\.claudeon Windows. - Copy the entire
.claudefolder to a safe location:cp -r ~/.claude /backup/claude-backup. - For each project you work on, copy the project’s
.claudesubfolder (if it exists) and any.mcp.jsonfile. - Export a list of installed npm global packages if you used any Claude Code plugins:
npm ls -g --depth=0and save the output. - If you use environment variables for API keys or proxy settings, note them down or export them to a file.
- Test your backup by listing the contents of the copied folder to ensure it’s not empty.
Rebuilding the Server: Fresh Install Steps
Once your backup is safe, you can rebuild the server. The exact commands depend on your OS, but the general flow is the same.
- Install Node.js (version 18 or newer is typical) and npm, if they aren’t already present.
- Install the Claude Code CLI globally:
npm install -g @anthropic-ai/claude-code(or use the native installer if that’s what you had). - Restore your backup: copy the
.claudefolder back to your home directory. - Run
claudein a terminal to start the interactive session. It will detect your existing credentials and skip the login prompt. - If it asks for login anyway, run
claude /loginand authenticate with your Anthropic account or API key. - Verify your settings are intact by checking
claude /configor opening the settings file. - Reinstall any global npm packages you had for plugins:
npm install -g package-name.
Common Problems and Fixes
Even with a good backup, you might hit a few snags. Here are the most frequent issues and how to resolve them.
- Credentials not recognized: If the backup is from a different OS version or the file permissions changed, Claude Code may ignore it. Fix by chmod 600 on the credential files or re-authenticating.
- MCP servers fail to start: The server paths in your config may point to old locations. Update
.mcp.jsonwith the new server URLs or commands. - Settings file version mismatch: If the new CLI version expects a newer schema, it may reset some fields. Back up your old settings and manually merge them.
- Missing environment variables: If you use a proxy or custom API endpoint, those are not stored in the config folder. Re-export them in your shell profile.
- Conversation history gone: If you didn’t back up the project-level
.claudefolder, old sessions won’t appear. You can still start fresh, but you lose that context.
What Not to Back Up
It’s tempting to copy everything, but some files are better left behind. Avoid backing up node_modules directories or any build artifacts—they will be recreated by npm install. Also, don’t copy over system-specific paths like /usr/local/bin; you’ll reinstall those via package managers. Finally, skip any cache files that are purely temporary; they will regenerate.
Security Considerations
Your .claude folder contains authentication tokens—treat it like a password manager. When you copy it to a backup location, ensure that location is encrypted or at least not world-readable. On the new server, set strict permissions: chmod -R 700 ~/.claude. If you use a shared server, consider using a separate user account for Claude Code to limit exposure. And never commit the config folder to a public repository.
Frequently Asked Questions
Do I need to back up the entire .claude folder or just specific files?
Back up the entire folder. It’s small (usually under a few MB) and contains all the credential and settings files. Picking individual files risks missing a new file format in a future version.
Will my API key be in the backup?
Your authentication token is stored in the config folder, but your raw API key is not. If you use an API key via environment variable, that key is not in the backup—you’ll need to re-enter it manually.
Can I move my Claude Code setup to a different operating system?
Yes, but with caveats. The config files are cross-platform, but file paths in your settings (like MCP server commands) may need updating. Also, the CLI installer differs between Linux, macOS, and Windows.
What if I lost my backup and I’m already on the new server?
You can still reinstall the CLI and log in again. You’ll lose conversation history and custom settings, but you can recreate them. Check if you have any cloud backups or version-controlled dotfiles.
How do I know if my backup is complete?
After copying, run du -sh ~/.claude on the old server and compare it to the backup size. Also, open the backup and verify that settings.json exists and contains your custom instructions.
Does reinstalling Claude Code affect my Anthropic account?
No. Your account is tied to your login credentials, not the server. Reinstalling the CLI does not change your account status, billing, or usage history.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.