Claude Code

The Claude Code desktop app attaches to a workbench over SSH using its Connect to SSH host feature. Claude Code then runs inside the container - against your repos, tools and services - while the app stays on your host. Like the other editors, it connects to the SSH host monoceros apply set up for you.

Note

acme is just a sample workbench name - it’s whatever you passed to monoceros init. Substitute your own throughout.

Note

Add the claude-code feature to the workbench, even if you only ever attach the desktop app over SSH. It’s what keeps your chat history across monoceros apply - without it, every rebuild starts you on an empty history. See Keep your chat history across rebuilds.

Prerequisites: Docker is running and the workbench is applied and up (monoceros apply acme, check with monoceros status acme). On Windows, make sure the container is on a current runtime (monoceros upgrade acme) - see the note below.

Connect

1. Open the environment picker (bottom-left, it reads Local by default) (1), and under SSH choose Add SSH host… (2).

   

2. Fill in the connection: Name a friendly label, e.g. monoceros-acme (1); SSH Host node@monoceros-acme (2) - the host comes from the SSH config monoceros apply wrote for you. Leave SSH Port and Identity File empty (they come from the config too). Then click Add SSH connection (3).

   

3. Confirm the trust prompt “Connect to SSH host?” with Connect (1). It’s remembered for next time.

   

4. The host is now in the bottom-left environment bar. Click the small Select folder… button next to it (right of where you just added the SSH host) to open the folder picker. In Select Remote Folder, enter your repo path under /workspaces/acme/ - e.g. /workspaces/acme/projects (1) - and click Select Folder (2).

   

5. Confirm the folder trust prompt that follows - same idea as the host trust, scoped to this folder.

The app connects and starts Claude Code in the container.

Note

The first connection can take a moment: the app downloads and deploys its remote server into the container before the session opens. Later connections reuse it and are fast.

No install, no login inside the container

Two things you might expect to set up, and don’t have to:

• Nothing to install or bake in to run Claude. On first connect the desktop app deploys its own remote server and CLI into the container (downloaded by the app, not baked into your image). The claude-code feature is still worth adding - it’s what keeps your chat history across rebuilds (see below).
• No separate sign-in. The app uses the account you’re already signed into on your desktop and passes that login to the remote session. You are not asked to authenticate inside the container, and no credentials are stored there.

The container only needs what monoceros apply already gives it: a running workbench with the built-in SSH server (runtime >= 1.2.0).

Keep your chat history across rebuilds

monoceros apply recreates the container from scratch - it tears down the old one and builds a fresh one. Claude Code keeps your conversations inside the container under ~/.claude. Unless something maps that directory to your host, a rebuild takes your chat history with it, and the app opens on an empty history after the next apply.

The fix is the claude-code feature. Adding it to the yml gives ~/.claude a persistent home mount, so your conversations - and Claude’s config - survive every apply:

monoceros add-feature acme claude
monoceros apply acme

Note

Without the feature the app still connects fine - its downloaded remote server lives on a separate persistent volume - but each apply starts you with an empty chat history. The feature is what makes the history stick.

The feature also installs the Claude Code CLI in the container and, on each apply, writes ~/.claude/settings.json from the yml (its permissionMode). Both sit happily next to the desktop app’s own backend: they share ~/.claude but are separate binaries.

Opening a browser

When Claude opens a URL from inside the container - to show you the running app, a link, an OAuth page - Monoceros relays it to your host browser automatically. The container is headless; there is nothing to configure.

Windows / WSL

Works, with one wrinkle handled for you. The desktop app’s SSH client can’t use the portless transport the other editors use on Windows, so monoceros apply (running in WSL) sets up a direct host-loopback port for the app and records the host key for you. This needs a current runtime. If the app times out or refuses the connection on Windows, move the container to the latest runtime and reconnect:

monoceros upgrade acme

On macOS and Linux there is nothing extra to do.

Trouble?

If a connection fails right after you changed something, fully quit and restart the app (it caches the connection until then), then reconnect. More in the IDE FAQ.