claude-code-dev-container

A self-hosted development container that runs Claude Code alongside a full PHP / Go / Node / Python toolchain, reachable over SSH from VS Code Remote-SSH and from the Claude mobile app.

It runs on an Unraid box, but nothing here is Unraid-specific beyond the nobody:users (99:100) uid convention and the share paths.

The point of it: one always-on box holds every repo and every Claude session. You open a repo in VS Code from your laptop, and pick the same work up on your phone without the laptop staying awake.

conf.d/      client side: the dev* commands          (fisher installs these)
completions/ client side: tab completion for them    (fisher installs these)
container/   server side: image, entrypoint, helper scripts
install.fish fisher-less installer, symlinks into ~/.config/fish

conf.d/ and completions/ sit at the repo root because that is the only place fisher looks. Fisher copies functions/, completions/, conf.d/ and themes/ from the root and ignores everything else, so container/ and this README are simply skipped.

container/rebuild.sh is the source of truth for how the container runs. It is not defined by an Unraid template, so a change made through the Unraid UI or an ad-hoc docker run is lost the moment the container is removed. Edit the script instead.

./container/rebuild.sh

Only two volumes survive a rebuild:

Anything installed into the image filesystem at runtime is discarded. Put it in the Dockerfile.

/home/dev is bind-mounted at runtime and never built into the image, which is what .dockerignore is for: without it the ~5 GB home is sent to the daemon as build context on every build.

Base is Debian sid, so most of this comes straight from apt at whatever version sid currently carries. Versions below are what the running image has today, not pins. Only the three ARG lines at the top of the Dockerfile are pinned.

Runtimes

PHP extensions worth calling out

Package and task managers

Browser and media

Shell and CLI

Both fd and bat are symlinked into /usr/local/bin because Debian ships them as fdfind and batcat to avoid name clashes.

Both are already handled, and both cost real debugging time to find:

pam_loginuid makes SSH silently do nothing. sshd in a container cannot write /proc/self/loginuid. PAM runs the rest of the stack, the MOTD even prints, then the session is marked failed and sshd closes it without exec-ing your command. SSH appears to connect, then exits 254. The Dockerfile downgrades that module to optional, the standard container fix, which avoids running privileged.

Claude Code is deliberately not installed in the image. An npm global install lands in root-owned /usr/local, which the dev user cannot write, so every auto-update dies with no_permissions. The entrypoint installs the native build into the persisted home instead: dev owns it, it survives an image rebuild, and it can update itself.

Host SSH keys are persisted in /home/dev/.sshd too, otherwise every rebuild trips VS Code's "REMOTE HOST IDENTIFICATION HAS CHANGED" warning.

Add to ~/.ssh/config on your workstation:

Host tower
    HostName your-host.example
    User root
    IdentityFile ~/.ssh/id_tower
    IdentitiesOnly yes

Host tower-dev
    HostName your-host.example
    Port 2222
    User dev
    IdentityFile ~/.ssh/id_tower
    IdentitiesOnly yes

tower reaches the Docker host, tower-dev reaches the container. Put your public key in /home/dev/.ssh/authorized_keys inside the volume. The fish commands use both aliases, so keep the names or edit fish/conf.d/tower.fish.

With fisher:

fisher install mbolli/claude-code-dev-container
fisher remove  mbolli/claude-code-dev-container

Without fisher:

./install.fish            # symlink into ~/.config/fish
./install.fish --uninstall

install.fish symlinks, so the file you edit is the file you commit. Existing regular files are moved to <name>.pre-install rather than overwritten.

Fisher refuses to install over files it does not own, with Cannot install: please remove or move conflicting files first. If you already have ~/.config/fish/conf.d/tower.fish or any completions/dev*.fish from a manual install, remove them first (or ./install.fish --uninstall if they are symlinks from this repo).

Every command that takes a repo accepts swisscyberguard, /develop/swisscyberguard or develop/swisscyberguard, and tab-completes against the live repo list (cached 10 minutes, with live descent into subdirectories).

entrypoint.sh starts a Remote Control host in /develop under tmux, in same-dir mode with capacity 8. same-dir rather than worktree because /develop holds many repos and is not itself a git repository, which worktree mode requires. Press w in the pane to toggle when the cwd is a single repo.

devlink gives you the URL and QR code to open on your phone.

Two things that are easy to get wrong:

One Remote Control process serves one directory, and the phone can only start sessions where one runs. The /develop host covers /develop itself; sessel serve runs one more per recently used repo, so those show up on the phone too. The entrypoint starts it at boot and it re-checks hourly.

Every session is on the phone. The container's settings turn on remoteControlAtStartup, and devwork and sessel also pass --remote-control explicitly, named after the repo or the session's title.

sessel (in container/sessel, Go, built into the image) knows every Claude session in the container by either of its two ids: the transcript uuid, which claude --resume takes, and the Remote Control id (session_01…, also cse_01… or the end of a claude.ai/code URL), which the phone shows. The Remote Control id changes every time a session is re-bridged, so the id on the phone is often an older one; sessel resolves all of them.

Run it with no arguments for the browser, from the laptop as sessel or devresume:

The same things are subcommands: sessel ls, open, peek, rename, rm, new, serve, resolve, json. sessel --help lists them.

Delete is real. It removes the transcript, the session's subagent and tool result directory, its file history, uploads, session env, scratchpad, registry records and the per-process key files. A running session is stopped first. Your prompt history (~/.claude/history.jsonl) and the project's memory stay. The session's entries on claude.ai are out of reach and stay listed there. sessel rm -n <id> shows exactly what would go.

A session is live only if its pid still belongs to the same process: pids start from 1 after every rebuild, so an existing pid is often someone else.

Claude sessions are server-side objects, separate from the local transcript UUIDs under ~/.claude/projects. The entrypoint snapshots the session registry (~/.claude/sessions/*.json) and each directory's bridge-pointer.json before the host starts, because new processes reuse the old pids and the host rewrites its pointer within a second. rebind-sessions.sh then brings back every bridged session active in the last REBIND_MAX_AGE_H hours: spawner sessions as windows in the rc tmux session, interactive --remote-control sessions resumed from their transcript in a tmux session of their old name. It skips only the session the host reclaims itself.

Tunables, as environment variables read by the entrypoint:

cat /tmp/rebind.log in the container shows the last run.