Try Turborg Free → Open App →
← All posts

Stop Re-Reading the Whole Repo: Give Your AI Agent a Persistent File System via MCP

October 26, 2026 · 4 min read · The xShellz Team

TL;DR

  • Claude Code connects to an xshellz.box over SSH with claude mcp add xshellz -- ssh -p <port> agent@<host> xshellz-mcp.
  • The box runs Ubuntu 24.04 LTS 24/7 with no idle timeout, and /root is the persistent home that survives image rebuilds.
  • Builds run on the remote box, not your laptop, so you can close the lid and the agent keeps working.

You connect Claude Code to a remote xshellz.box by registering the box as an MCP server over SSH, using a single claude mcp add command. The box runs Ubuntu 24.04 LTS, stays on around the clock, and keeps /root persistent across image rebuilds. That gives the agent a real filesystem instead of a context window.

We build and operate xShellz: the borg terminal agent, the Agent Shell boxes and the hosted model gateway behind them. Everything below is what we run in production ourselves, not a demo.

How can I connect Claude Code to a remote Linux box using MCP so it has a persistent environment?

Run claude mcp add xshellz -- ssh -p <port> agent@<host> xshellz-mcp on your local machine. This tells Claude Code to treat a remote xshellz.box as a tool server. The box runs Ubuntu 24.04 LTS full time with no idle timeout, so the environment persists after you close the laptop. /root is the permanent home directory; everything else on the box resets only when the image is rebuilt. That gives your agent a stable place to keep files and state between sessions.

what is MCP and how does it work with Claude Code?

MCP, the Model Context Protocol, is an open standard for connecting AI tools to external systems. Claude Code uses MCP to talk to servers that expose files, shell commands, or other services. When you add an MCP server over SSH, Claude Code can call tools on that remote machine as if they were local, without loading the files into the model's context window. That keeps the context small, because the agent fetches only the specific files it needs for the task. The spec is at modelcontextprotocol.io.

how do I wire an xshellz.box into Claude Code as an MCP server over SSH?

First, have an xshellz.box running and know its SSH host and port. Then run this command on your laptop:

claude mcp add xshellz -- ssh -p <port> agent@<host> xshellz-mcp

The agent@<host> user is preconfigured on every box for MCP access, separate from the root shell you use with ssh -p <port> root@<host>. After the command runs, Claude Code lists xshellz among its tools the next time you start it. From then on, the agent can read, write, and run commands on the remote box over the same SSH connection.

why is a remote file system better than just pasting code into a chat?

Pasting code into a chat loads every line into the model's context window, which you pay for and which slows responses. A remote file system via MCP lets Claude Code open only the files it needs, when it needs them. The state also persists: /root survives image rebuilds, so checkouts, build artifacts, and configuration stay put across sessions. The box never sleeps, with zero idle timeout, so a long-running task keeps going even if you disconnect. That matches how a human engineer works: a persistent checkout, not a conversation transcript.

can I run heavy builds on the remote box via the agent without killing my laptop?

Yes. The xshellz.box runs on its own hardware, not your laptop, so any command the agent runs through MCP executes on that remote machine. Compiling a large project uses the box's CPU and memory, not yours. You can start a build inside tmux on the box, or ask Claude Code to run it directly, and it continues while your laptop is closed. Every box ships with build-essential, git, Node 22, and Python 3, so common build toolchains are already installed. The box stays on 24/7 with zero idle timeout.

Frequently asked questions

Do I need a separate subscription for the MCP server?

No. The MCP server is built into every xshellz.box, and the xshellz-mcp command is preinstalled. You only need a running box and the local Claude Code client.

What happens to my files if the box image is rebuilt?

/root is the persistent home and the only path that survives a rebuild. Everything outside /root is ephemeral and resets. Keep code, configs, and build outputs in /root or under /home, which points into /root.

Can I use other coding agents besides Claude Code with this MCP server?

Yes. The box ships with 6 preinstalled agent CLIs, but the MCP server is a standard endpoint. Each agent has its own MCP configuration syntax; the command shown above is specific to Claude Code.