How Much RAM Does Your Claude Code VPS Need?
A Claude Code VPS is a rented VM running the CLI and your development tools. Measure the entire workload on a pilot VM, then set an initial concurrency cap from the remaining memory.
Measure whole jobs with isolated checkouts
Use separate Git worktrees when agents are editing the same repository in parallel. Benchmark the jobs that actually overlap, including test runners and language servers, because those processes share the VM even when files are isolated. Measure VM-wide memory in use with one consistent counter. Capture the idle baseline after host services start, the peak during each isolated job, and the peak during an overlap run. For an illustrative 8 GiB VM with 1.25 GiB already in use and 1 GiB reserved, two jobs adding 2.25 GiB each leave 1.25 GiB of headroom above reserve. Three cross the reserve by 1 GiB. Repeat with a cold dependency cache and record elapsed time, swap activity, and any killed processes. Use a slower overlap run with healthy memory as a reason to investigate CPU or disk contention before buying RAM.
Common workflows - Claude Code DocsRecreate an interrupted workspace on the candidate image
Run a replacement exercise alongside the load test if your VPS hosts sessions that must outlive the VM. For an Agent SDK deployment, the documented SessionStore can mirror transcripts for a resume from a matching working directory. Prepare the repository revision and any needed uncommitted changes independently, then record the time spent restoring the checkout, rebuilding dependencies, and resuming the session. In the exercise, ask for a harmless fact from the prior conversation and verify that a known local-only patch is present in the restored checkout. A correct answer paired with a missing patch exposes two different recovery outcomes. Compare candidate images on both checks with cold caches. An image that saves a minute on dependency setup can matter more to your recovery objective than extra RAM on a machine that already meets your peak concurrency.
Persist sessions to external storage - Claude Code DocsSize disk and memory from one real run
Provision a candidate Linux VM and install Claude Code using the documented path for its operating system. Authenticate in the terminal and prompt the agent to locate a known file without editing it. After that succeeds, run the actual build or test suite from a disposable checkout. Record peak memory, free disk after the run, and elapsed time. Repeat with the concurrency you expect on an ordinary busy day.
In an illustrative disk test, the base system uses 6 GB, two worktrees with dependencies use 9 GB each, and caches and logs use 4 GB. That totals 28 GB before any additional headroom for growth or updates. A nominal 30 GB disk leaves roughly 2 GB before filesystem overhead. Test more capacity or reduce the number of simultaneous worktrees if that margin is too small for your update process.
Overview - Claude Code DocsDiagnose collisions before buying more CPU
Use a separate Git worktree for each concurrent Claude Code session that edits the same repository. Give each session its own task and check each branch diff before merging. A successful trial ends with the expected edits isolated on their intended branches, tests passing, and no unexpected changes in the other worktree. Include duplicate dependencies in the disk budget if each checkout installs its own copy.
If both sessions finish but a generated file appears on the wrong branch, check the working directory and where the build writes artifacts. A shared output path can still collide across separate checkouts. If one job instead gets killed and the system reports memory pressure, rerun the workload serially. Compare completion time with your deadline before deciding whether to add RAM or reduce concurrency.
Common workflows - Claude Code DocsRestore the workspace to a replacement VM
Write down the repository revision, the location of uncommitted changes and build artifacts, and how an authorized operator restores credentials. On a disposable replacement VM, restore the workspace and run a known test. If conversation continuity matters, require a second check that an existing session resumes and can see the expected files at the intended path. A successful transcript restore and a successful code restore are separate results.
If your application uses the Claude Agent SDK, its SessionStore adapter can copy transcripts to your own storage. Resume from a working directory that matches the original run and verify that the replacement host has the corresponding project files. If the conversation returns but the previous edits are missing, check your workspace backup. Copying the transcript preserves the conversation while the workspace still needs its own recovery path.
Persist sessions to external storage - Claude Code Docs