Claude Code on a server: one copy of the work, and you attach to it

Closing the laptop killed 27 % of my long agent runs. Syncing files to a server is the wrong fix. Here is the one that works, and an open-source setup you can run.

If you work in a terminal with an AI agent, the session is the work. And a terminal session dies with your laptop. You close the lid, the connection drops, and the agent's half-finished run is gone.

I lost 27 % of my long design runs that way, to the lid or to a sleep timer. On the laptop the fix was a sleep inhibitor around every session. For runs that should keep going when the laptop is off, I built agent-workspace: Claude Code and Codex on a server, with your laptop as the window into them.

cd ~/projects/my-app
agent          # opens a session on the server, in this repo
# close the lid, go home, open a terminal
agent          # the same session, still running

Syncing files is the wrong fix

The first idea everyone has is to sync the project folder to a server and run the agent there. It does not survive contact with a real repo. Two-way file sync, plus an agent rewriting files, plus git's own files, means conflicts all day. .git/index, lock files and node_modules fight the sync tool. A workflow with one git worktree per parallel agent makes so much churn that no sync tool keeps up.

What works is simpler: there is one copy, on the server, and you attach to it. Nothing is duplicated, so there is nothing to reconcile.

Three layers, and only one goes both ways

Everything else follows from that rule.

Code travels through git. The server clones a repo the first time you run agent inside it. GitHub was always the sync layer. The size of your local projects folder does not matter, because nothing is mirrored.

Worktrees are recreated, never synced. A worktree is derived state: git worktree add builds it again from a branch. Branches travel between machines, directories do not. This is what makes a many-agents workflow possible on a server at all.

Config goes both ways. Agent instructions, subagents, skills and hooks live in a dotfiles repo applied on both machines, with host-specific values templated. The sync checks the server first and commits anything changed there before it applies local changes. A one-way sync would quietly throw away a rule you edited on the server.

Secrets travel encrypted. .env files are not in git, so a clean clone on the server cannot run anything. A small encrypted vault, one folder per project, ships decrypted copies into the workspace. The decryption key stays on the laptop.

Sessions live in one place on purpose. They exist only on the server.

The price is one habit: uncommitted work does not travel. Commit and push before you switch machines, or it stays where it is. That is the whole cost of having no merge conflicts anywhere else.

Moving a conversation mid-thought

The most useful part: agent handoff takes the Claude Code conversation you are in right now and reopens it on the server, already resumed. You type "continue".

It works because Claude Code keeps each conversation as one file under ~/.claude/projects/, named after the folder it ran in, and claude --resume <id> reopens it. The handoff rewrites the absolute paths inside the file from your local checkout to the server's, copies it over, and starts a session with claude --resume.

Inside a running conversation, /agent-handoff does the same. Claude Code sets CLAUDE_CODE_SESSION_ID in the environment, so the command knows which conversation to move without asking. That matters, because a slash command has no terminal to show a picker in.

What to know before you rely on it:

  • The conversation file format belongs to Claude Code and can change between versions.
  • Only paths inside the repo are rewritten. The agent may mention files outside it that do not exist on the server.
  • Never resume the same conversation on two machines at once. Use --fork-session if you want a branch rather than a move.

What the server runs

One pod on a small Kubernetes cluster. A single server with k3s is enough.

  • The workspace, as user 1000, not root. This one is required: Claude Code refuses --dangerously-skip-permissions when it runs as root.
  • Docker beside it, so projects that expect a database and a built image start with docker compose as they do on a laptop. Both containers share a network, so compose ports land on the workspace's own localhost.
  • A real browser for Playwright, whose system libraries an init container installs once.
  • Two volumes: 50 GB for home, 20 GB for Docker's cache. The first boot takes a couple of minutes; restarts take seconds, because everything persists.

You reach it with kubectl, not SSH. That helps when port 22 is closed.

The one security trade-off

Real docker compose needs a privileged Docker container, and a privileged container can reach the node. Decide whether that is acceptable before you deploy, especially if the node runs anything else. If you do not need Docker, delete that container and everything else still works.

What the setup does avoid: the usual Docker-in-Docker recipe opens the Docker API on a network port with no authentication, reachable by every pod in the cluster. Here the daemon has no network listener at all. Its socket sits on a shared volume that only the workspace's group can open.

Two things that will bite you

The screen is stuck at the wrong size. The terminal multiplexer sizes a session to its smallest attached client, and a dead client from an old connection pins it. agent fix clears it.

Two terminals show the same session. A bare agent reuses a session nobody is attached to and opens a new one only when they are all busy. That one rule covers both "give me my session back" and "give me another terminal". agent -n api forces a new one named repo@api. agent -m mirrors on purpose.

What it does not do

  • One replica. Sessions live on one volume by design.
  • If the pod restarts, running processes die. Files and conversations survive, and claude --resume brings the conversation back.
  • Tools that need your real desktop browser, such as a browser extension, stay on the laptop.
  • Most tool versions float to the latest at build time. Pin them if you need the same build twice.

The code is MIT-licensed: github.com/niro58/agent-workspace. How the sessions work together once they run is in My AI agent crew.

More posts

All posts →
  1. 21 Nov 2026

    Same agent, rebuilt workspace, a quarter of the bill: what EnvOpt showsA new arXiv paper leaves the model and the harness alone and lets another AI rebuild the workspace the agent works in. On 200 test tasks, the same Claude Haiku 4.5 agent cost $42.36 before and $11.55 after, and passed more tasks.

    AI · 7 min
  2. 21 Nov 2026

    CLAUDE.md vs AGENTS.md: which one Claude Code reads, and why I keep only oneWhen a repository has both files, Claude Code reads CLAUDE.md and leaves AGENTS.md alone unless you import it. I found five of my repositories set up the wrong way round: the real instructions in AGENTS.md, and a CLAUDE.md that only pointed at it.

    How I build · 5 min
  3. 20 Nov 2026

    Running several Claude Code agents at once: worktrees, handoffs and one check per phaseWhat broke when I put many Claude Code agents on the same repositories, and the four rules that stayed: one worktree per agent, small file-disjoint jobs, a rewritten handoff, and one full check per phase.

    How I build · 5 min