ThisCalculator

Everyday

Rebuild a Server for Claude Code: Backups & Next Steps

Updated · Standard formula, shown below

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.json inside that same .claude directory. 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.json at 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.

  1. Find the config directory: run echo $HOME/.claude on Linux/macOS, or check %USERPROFILE%\.claude on Windows.
  2. Copy the entire .claude folder to a safe location: cp -r ~/.claude /backup/claude-backup.
  3. For each project you work on, copy the project’s .claude subfolder (if it exists) and any .mcp.json file.
  4. Export a list of installed npm global packages if you used any Claude Code plugins: npm ls -g --depth=0 and save the output.
  5. If you use environment variables for API keys or proxy settings, note them down or export them to a file.
  6. 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.

  1. Install Node.js (version 18 or newer is typical) and npm, if they aren’t already present.
  2. Install the Claude Code CLI globally: npm install -g @anthropic-ai/claude-code (or use the native installer if that’s what you had).
  3. Restore your backup: copy the .claude folder back to your home directory.
  4. Run claude in a terminal to start the interactive session. It will detect your existing credentials and skip the login prompt.
  5. If it asks for login anyway, run claude /login and authenticate with your Anthropic account or API key.
  6. Verify your settings are intact by checking claude /config or opening the settings file.
  7. 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.json with 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 .claude folder, 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.