Blog · · 10 min read
isolde: a separate Linux desktop for every project
isolde gives each project directory its own Linux desktop in Docker, reachable over RDP: a real browser, a terminal and a separate home for Claude Code in every project.
I run Claude Code on most of my projects, and I wanted it to have its own computer for each one: a desktop with a real browser, a terminal, and a home directory that stays separate from everything else. isolde is the small tool I built for this. It gives each project directory its own Linux desktop in Docker, which you reach over RDP.
The idea of a development container isn't new. What isolde adds is a full desktop, so you can watch what Claude Code is doing in a browser, log in to web portals yourself, and step in when needed. I've been using it daily, and this article walks through the basic setup and usage.
The source is on GitHub: github.com/dmitrymatveyev/isolde.
What you get
When you run isolde in a project directory, it starts a container with:
- Your project at
/workspace: the directory you ran it from is mounted into the container, so changes appear on the host straight away. - A home of its own: each project directory gets its own
/home/dev, stored in a Docker volume. It keeps your settings, logins and history when the container stops or the image is rebuilt. - A desktop over RDP: XFCE on Ubuntu 24.04, served by xrdp.
- Tools for working with Claude Code: Claude Code, the kitty terminal, tmux, Chromium and Playwright, plus common tools such as
git,gh,ripgrepandjq.
Two projects never share a home, so a login, a browser profile or a configuration change in one project doesn't reach the others.
Requirements
- Docker
- An RDP client
bashandsha256sumon the host
So far I've only tested isolde on my own Linux machine. Docker Desktop on macOS or Windows and ARM hosts haven't been tried yet.
Step 1: Build the image
Clone the repository and build the image from it:
git clone https://github.com/dmitrymatveyev/isolde.git
cd isolde
docker build --build-arg HOST_UID=$(id -u) --build-arg HOST_GID=$(id -g) -t isolde .
The two build arguments give the container's dev user the same UID and GID as your host user. Files that Claude Code or you create in /workspace are then owned by you on the host, not by root.
The first build takes a while, because it installs the desktop, Node.js, Claude Code and Chromium.
Step 2: Put isolde on your PATH
Link the script into a directory on your PATH:
ln -s "$PWD/isolde" ~/.local/bin/isolde
Use a symlink rather than a copy, because the script needs a file that sits next to it in the repository.
Step 3: Start a desktop for a project
Go to the project you want to work on, choose a password for the desktop, and run isolde:
cd ~/projects/foo
export RDP_PASSWORD='choose-something'
isolde
It prints the address to connect to:
/home/you/projects/foo -> RDP at 127.0.0.1:49153 (user: dev)
Docker picks a free port each time a container starts, so the port can change between starts. Running isolde again in the same directory prints the address of the running container without starting a new one.
Step 4: Connect over RDP
Open your RDP client and connect to the printed address:
- Enter the address, for example
127.0.0.1:49153. - Log in as
devwith yourRDP_PASSWORD. - Choose the
Xorgsession if you're asked. - Accept the certificate warning. xrdp uses a self-signed certificate.
You now have an XFCE desktop. Your project is at /workspace, and kitty and Chromium are set as the default terminal and browser. The port is bound to 127.0.0.1, so only the host can reach it.
Step 5: Run Claude Code
Open a terminal on the desktop and start Claude Code:
cd /workspace
claude
The first time, log in as usual. The login is stored in the project's home, so you only do this once per project directory.
Chromium is available from the applications menu or with the chromium command, and it runs with its sandbox turned on.
Step 6: Open a shell from the host
You don't need the desktop for terminal work. From the project directory on the host, run:
isolde shell
This opens a shell in /workspace inside the same container, using your terminal's color settings. If the container isn't running, it's started first, so RDP_PASSWORD has to be set. Typing exit closes the shell and leaves the container running.
tmux is included and set up for Claude Code, so a session survives closing the shell or disconnecting from RDP. Reattach later with tmux attach.
Step 7: Let Claude Code use a logged-in browser
This is the main reason I built isolde. Many tasks involve web portals that need a login, often with MFA, which an automated browser can't get through on its own. Instead, you log in yourself in a Chromium window, and Claude Code connects to that window.
In a terminal on the desktop, start Chromium with a dedicated profile and a debugging port:
chromium --user-data-dir="$HOME/.config/claude-browser" --remote-debugging-port=9222Log in to the portals you need in that window.
Give Claude Code browser tools through Playwright MCP. You only need to do this once per project:
claude mcp add playwright -- npx @playwright/mcp@latest --cdp-endpoint http://localhost:9222Start
claudeand ask it to work in the portal.
Keep the window visible so you can follow along and handle a CAPTCHA or an expired session. Keep in mind that Claude Code can do anything you could do in those portals, and that page content can try to give it instructions. Leave permission prompts on, review anything that submits, pays or deletes, and close the window when you've finished, because anything in the container can control the browser while the debugging port is open.
Step 8: Stop the container
From the host, find the container with docker ps and stop it:
docker stop isolde-foo-<hash>
Logging out of XFCE ends only the desktop session, and the container keeps running.
What persists and what doesn't
Containers are removed when they stop, so only two locations survive:
| Location | Stored in | Kept |
|---|---|---|
/workspace |
Your project directory on the host | Always |
/home/dev |
A Docker volume for that directory | Until you delete the volume |
| Everything else | The container | Lost when the container stops |
This means:
- Install packages in the image: anything you install with
aptat runtime is gone after a restart. Add it to theDockerfileinstead. - Homes follow the path: renaming or moving a project directory gives it a new, empty home. The old volume stays until you delete it.
The README explains how to list and delete homes, update Claude Code, and connect from another machine.
A note on security
isolde keeps projects apart from each other, but it isn't a strong security boundary. Anything running in the container, including Claude Code, can change the mounted project and has full network access. See the Security section of the README before using it with anything sensitive.
Try it
isolde is open source under the Apache-2.0 license: github.com/dmitrymatveyev/isolde. If you try it, especially on macOS, Windows or an ARM machine, I'd like to hear how it went. Issues and suggestions are welcome.