Back Up Claude Code, Codex and OpenClaw on a VPS

Your AI agent's server holds more than code. Claude Code keeps your instructions, settings, skills and its notes to itself in your home folder, Codex CLI keeps its own in ~/.codex, and OpenClaw keeps its config, chat connections and sessions in ~/.openclaw. If the VPS is deleted, reinstalled or wiped by one bad command, your code may be safe on GitHub, but the setup that made the agent useful is gone. This guide lists what to keep for each tool, what to leave out, and a nightly routine with git, OpenClaw's own backup command and restic, plus a restore test. Commands are for Ubuntu 24.04 and Debian 12.

Quick answer: Push every repository to a private remote and check for work that never left the server with git log --branches --not --remotes. Back up ~/.claude, ~/.claude.json, ~/.codex and ~/.agents with an encrypted tool such as restic, but leave out the login files ~/.claude/.credentials.json and ~/.codex/auth.json and sign in again after a restore. Never copy OpenClaw's live ~/.openclaw folder, because its databases can be caught mid-write: run openclaw backup create --verify every night, back up those archives, and keep the workspace in a private git repo. Test a restore every month.

What to Save, Tool by Tool

Claude Code's directory reference lists these files, and its 30-day cleanup of old transcripts leaves auto memory alone. Claude Code adds .claude/settings.local.json to your global git excludes the first time it writes that file (not when you create it by hand), and its memory docs tell you to gitignore CLAUDE.local.md, so neither reaches your remote. Codex reads personal skills from $HOME/.agents/skills, outside ~/.codex (skills docs). If you set CLAUDE_CONFIG_DIR or CODEX_HOME, back up those folders instead.

Step 1: Get the Code Off the Server

An agent commits to the repository on the VPS, and nothing leaves the server until something pushes it. In each project, check three things:

cd ~/projects/myapp
git status
git log --branches --not --remotes --oneline
git stash list

git status shows uncommitted changes. The git log line lists commits on local branches that no remote-tracking branch contains, which catches a branch the agent created and never pushed (git log). git stash list shows stashes, which a push never sends. Commit and push what you want to keep to a private remote. If the agent pushes for you, give it a deploy key for that one repository, as our AI agent security guide explains.

For a repository without a remote, make a bundle, one file with every branch and tag. Run this in the project folder:

mkdir -p ~/Backups/git
git bundle create ~/Backups/git/myapp.bundle --all
git bundle verify ~/Backups/git/myapp.bundle

git clone ~/Backups/git/myapp.bundle myapp turns it back into a repository. Git's bundle docs prefer this to copying the repository folder, which can catch it halfway through a write. A bundle leaves out the working tree, the index and the stash, so restic still needs the folder for work in progress.

Step 2: Claude Code and Codex: Settings In, Logins Out

Back up both tools' folders whole, except the files that hold your logins. On Linux, Claude Code stores its login in ~/.claude/.credentials.json (authentication), and Codex caches its login in plain text in ~/.codex/auth.json or in the system's credential store (Codex authentication). Leave both out and sign in again after a restore. An old copy may not work anyway: OpenAI's CI/CD auth guide says not to share one auth.json between machines, and to replace it with a fresh login when an old file was restored or another machine rotated the token first.

Secrets also sit in files you do keep, so these belong in an encrypted backup, never in git:

• ~/.claude.json holds the MCP servers you added in local or user scope, including keys you passed with claude mcp add --env (MCP docs).
• ~/.codex/config.toml can hold keys in an MCP server's env table. bearer_token_env_var reads an MCP HTTP server's token from an environment variable instead (configuration reference).
• Transcripts are plain text. Claude Code writes file contents and command output to ~/.claude/projects/<project>/<session>.jsonl, so a .env file a tool read ends up there. Codex saves transcripts to ~/.codex/history.jsonl (advanced config).

Step 3: OpenClaw: Archive First, Then Copy

OpenClaw keeps its config, model and channel credentials, sessions and per-agent SQLite databases under ~/.openclaw. Its backup guide is blunt: never copy live .sqlite, -wal, -shm or -journal files, because "raw file copies of a live database can be torn or corrupt." Use its own command, which snapshots the databases safely while the Gateway runs. As the OpenClaw user:

mkdir -p ~/Backups/openclaw
chmod 700 ~/Backups
openclaw backup create --output ~/Backups/openclaw --verify
command -v openclaw

The archive covers state, config, credentials, every agent directory and, by default, the workspace, and --verify checks it after writing (backup CLI). Because the archive holds auth profiles and channel credentials, OpenClaw says to store backups encrypted and to restrict them like the state directory, which its secrets page keeps at 700.

To run it nightly, open crontab -e as the OpenClaw user and add this line, with the path command -v openclaw printed:

0 4 * * * /usr/bin/openclaw backup create --output "$HOME/Backups/openclaw" --verify >> "$HOME/Backups/openclaw-backup.log" 2>&1 && find "$HOME/Backups/openclaw" -name '*-openclaw-backup.tar.gz' -mtime +2 -delete

cron runs each line with /bin/sh and sets only a few variables, such as HOME (crontab(5)), which is why the full path matters. After a good archive, find deletes archives that are three or more days old (find(1)); restic keeps the history. Each archive is a full copy, which OpenClaw calls "a reasonable daily routine for small installs," and openclaw doctor prints a hint when the newest successful backup is more than 14 days old.

The workspace, with AGENTS.md, SOUL.md, MEMORY.md and the daily notes in memory/, is the agent's memory. OpenClaw's workspace page recommends a private git repository for it, and new workspaces get one automatically when git is installed. Commit and push it like any repository, and keep API keys and OpenClaw's state files, such as openclaw.json and the .sqlite databases, out of it.

Step 4: Add the Agents to restic

Our restic guide sets up an encrypted repository on another machine, an include list with /home and /root, and a nightly timer at 04:30, after the OpenClaw archive. With that in place, add three lines to the exclude list:

# /etc/restic/exclude.txt: add these lines
/home/*/.claude/.credentials.json
/home/*/.codex/auth.json
/home/*/.openclaw

restic matches patterns against the full path, a leading / anchors them and * doesn't match across a / (exclude rules). The third line skips the live OpenClaw folder, while the archives in ~/Backups/openclaw stay in. If an agent runs as root, add the same lines with /root in place of /home/*. To keep transcripts out as well, add /home/*/.claude/projects/*/*.jsonl and /home/*/.codex/history.jsonl. Memory files don't match those patterns, but you can no longer resume old sessions after a restore.

Step 5: Test the Restore

Every month, open a root shell, load the restic settings as in the restic guide and restore the agent folders into a scratch folder, with your own usernames in place of agent and openclaw:

sudo -i
set -a; . /etc/restic/env; set +a
restic restore latest --target /tmp/restore-test --include /home/agent/.claude --include /home/agent/.codex --include /home/openclaw/Backups/openclaw
diff /home/agent/.claude/CLAUDE.md /tmp/restore-test/home/agent/.claude/CLAUDE.md && echo SAME
ls /tmp/restore-test/home/agent/.claude/projects/*/memory/
ls /tmp/restore-test/home/agent/.claude/.credentials.json

--include can be given more than once (restore man page), and the files land under /tmp/restore-test with their full paths (restore docs). The diff should print SAME (compare any file you wrote if you have no global CLAUDE.md), the first ls should list your memory files, and the second should report that the file doesn't exist, which proves the login stayed out. Then hand the newest OpenClaw archive to the OpenClaw user, with its file name in place of NEWEST.tar.gz:

install -o openclaw -g openclaw -m 600 /tmp/restore-test/home/openclaw/Backups/openclaw/NEWEST.tar.gz /home/openclaw/restore-check.tar.gz

Logged in as that user, run openclaw backup verify ~/restore-check.tar.gz, which checks the manifest, the payload and the database snapshots. Then delete both copies: rm ~/restore-check.tar.gz as that user and rm -rf /tmp/restore-test as root.

Twice a year, rebuild on a spare VPS. Create the same users and keep the same project paths: Claude Code names each folder under ~/.claude/projects/ after the project's path, such as -home-user-work-my-repo for /home/user/work/my-repo, and files local-scope MCP servers in ~/.claude.json under that path too. Set up restic as in the "After losing the VPS" part of the restic guide, then, in a root shell with the restic settings loaded, restore and copy back:

restic restore latest --target /srv/restore --include /home/agent --include /home/openclaw/Backups
cp -a /srv/restore/home/agent/. /home/agent/
cp -a /srv/restore/home/openclaw/Backups /home/openclaw/
chown -R agent:agent /home/agent
chown -R openclaw:openclaw /home/openclaw/Backups

As the agent user, install Claude Code and Codex as in our Claude Code and Codex guides, then sign in with claude auth login and codex login --device-auth. In a Claude Code session in your project, /memory lists your CLAUDE.md files and can open the auto memory folder. For Codex, run codex --ask-for-approval never "Summarize the current instructions." from a repository root, and it should echo the guidance from your global and project AGENTS.md files (AGENTS.md docs).

For OpenClaw, install it as in our OpenClaw guide, then follow its migration steps as the OpenClaw user, with the newest archive's name in place of NEWEST.tar.gz:

openclaw gateway stop
openclaw backup restore ~/Backups/openclaw/NEWEST.tar.gz --target ~/openclaw-restored
mv ~/.openclaw ~/.openclaw.fresh
mv ~/openclaw-restored/*/payload/posix/home/openclaw/.openclaw ~/.openclaw
openclaw doctor
openclaw gateway restart
openclaw status

Restore never writes over live state. It unpacks each original path under payload/posix/, and its manifest.json lists them if your state lived elsewhere. WhatsApp may need relinking, and plugins get their dependencies back with openclaw plugins update <id>. Time the whole drill; our restore drill guide turns it into a runbook.

If It Still Fails

• Claude Code has forgotten a project's memory. The project now sits at another path or under another username, so its folder under ~/.claude/projects/ has a different name. Put the project back at its old path.
• Codex returns 401 after you restored an old auth.json. The token was refreshed elsewhere or has expired. Run codex login --device-auth again.
• openclaw backup restore refuses the target. The target must be new or empty and outside the live state folder, and there's no force option.
• OpenClaw's channels look logged out and its sessions are empty. The Gateway runs with a different profile or OPENCLAW_STATE_DIR than the state you restored. Start it with the same one, then run openclaw doctor.
• The Gateway can't read its credentials. Files copied as root or from another user can end up with the wrong owner. Run sudo chown -R openclaw:openclaw /home/openclaw/.openclaw and restart the Gateway.

FAQ

Can I keep my agent's settings in git instead of restic? The files you wrote, yes: ~/.claude/CLAUDE.md, settings.json, rules/, skills/ and agents/, plus ~/.codex/AGENTS.md, rules/ and config.toml once you've checked it for keys. Never commit ~/.claude.json, the two login files, transcripts or OpenClaw's state files; of OpenClaw, only the workspace belongs in git.

Does Claude Code delete old sessions by itself? Yes. It deletes transcripts, checkpoints and other session files older than cleanupPeriodDays, 30 days by default, and keeps auto memory, your prompt history and your settings. Only a backup keeps older transcripts.

Is openclaw.json enough to move my OpenClaw agent? No. OpenClaw's migration guide says shared model auth lives in state/openclaw.sqlite, per-agent profiles in agents/<agentId>/agent/openclaw-agent.sqlite and channel state under credentials/. Move the whole state with openclaw backup create and openclaw backup restore.

What if a backup with my keys leaks? Replace every API key and token it held, and sign in again on your servers. OpenClaw's docs advise rotating credentials whenever you suspect a backup leaked. Keeping the logins out of the backup, as in Step 2, leaves fewer secrets to replace.

Are backups included with a Space-Node VPS? Not in the plan price; you can arrange them through a support ticket. With full root access on our AI agent VPS plans, you can also run this routine yourself and decide where the copies live.

Sources

All opened on 31 October 2026:

• Anthropic, Claude Code docs: The .claude directory, Authentication, Memory, MCP and Settings
• OpenAI, Codex docs: Config basics, Advanced configuration, Configuration reference, Environment variables, Authentication, Maintain Codex account auth in CI/CD, AGENTS.md, Rules, Memories and Build skills
• OpenClaw docs: Backup CLI, Backups, Migration guide, Agent workspace and Secrets and storage
• restic docs: Backing up, Restoring from backup and the restore man page for 0.14.0, the version in Debian 12
• Git: git-bundle, git-log and git-stash
• Debian 12 man pages: crontab(5), find(1), bash(1), install(1), cp(1) and chown(1)

Claude Code is made by Anthropic and Codex by OpenAI. Space-Node is not affiliated with or endorsed by Anthropic, OpenAI or the OpenClaw project.