claudepod
xzrq-net/claudepod
Nix Home Manager module that builds and runs a tiny container to isolate coding agents
Instalação
npx convez-ai xzrq-net/claudepod1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
claudepod is a Nix Home Manager module that builds and runs a tiny container.
This project is vibe-coded personal infrastructure. Treat it as a showcase of
container primitives, not an off-the-shelf product.
The container is meant to gently prevent a coding agent session from misusing ambient credentials like dotfiles. It is not a security boundary. Isolation model:
- dedicated container home (including
.claudeand.codex) and host~/srcare mounted read-write and shared between instances - current directory mounted read-write under
/projects/<name> - unrestricted Internet and local network access
- passwordless sudo into container root
- leaks host details like mount names and hardware info
- GPT 5.5 couldn't figure out a way to escape isolation
- host Nix store is fully readable (you don't keep secrets in there, do you?)
The overhead is ~20 MB RAM in systemd detritus and <1MB on disk for NixOS.
Everything else comes from the host Nix store. Time to start, run true and
shut down is around 1.2s on my machine.
Quick Start
Run Claude Code in the current project:
nix run github:xzrq-net/claudepod
Run Codex in the current project:
nix run github:xzrq-net/claudepod#gptpod
Commands
claudepod [-s] [-V] [-v path] [-v host:guest]... [--] [command [arg]...]
gptpod [-s] [-V] [-v path] [-v host:guest]... [--] [command [arg]...]
Options:
-s: start a login shell instead of the default agent mode.-V: verbose mode, shows systemd boot messages in the guest.-v path: mount the same host path at the same guest path.-v host:guest: mount a host path at a specific guest path.command [arg]...: run this command in the project directory instead of the default agent or shell.
Environment variables:
CLAUDE_CODE_*: forwarded into the guest session process.MAX_THINKING_TOKENS: forwarded the same way when set.
Builtin paths:
- State directory:
${XDG_DATA_HOME:-$HOME/.local/share}/claudepod - Source root mounted into the guest:
$HOME/src
Home Manager Usage
The flake exposes homeModules.default. Enabling it adds the claudepod and
gptpod commands to home.packages.
Example:
{
inputs.claudepod.url = "github:xzrq-net/claudepod";
outputs = { claudepod, home-manager, ... }: {
homeConfigurations.me = home-manager.lib.homeManagerConfiguration {
modules = [
claudepod.homeModules.default
{
programs.claudepod = {
enable = true;
# Function from guest `pkgs` to extra packages installed in the guest.
extraGuestPackages = pkgs: [
pkgs.nodePackages.pnpm
];
};
}
];
};
};
}
Nix Store Overlay
The guest Nix daemon is configured with:
NIX_REMOTE=local-overlay://?lower-store=unix%3A%2F%2F%2Fnix%2F.host-nix-daemon%2Fsocket&upper-layer=/nix/.rw-store/store&real=/nix/store&check-mount=false
Broken down:
local-overlay://: use Nix's local overlay store implementation.lower-store=unix:///nix/.host-nix-daemon/socket: lower-layer metadata queries go to a host-side proxy (claudepod-nix-proxy) over a bind-mounted socket. The proxy forwards a small set of read-only operations to the host nix-daemon and rejects everything else. Store contents still come from the read-only/nix/storemount.upper-layer=/nix/.rw-store/store: put guest-created store paths in the writable overlay upper layer. This is backed by tmpfs inside the container.real=/nix/store: expose the combined lower and upper store at the normal/nix/storepath used by guest processes.check-mount=false: skip Nix's overlay-store mount validation because it does not match the kernel overlayfs format reported in/proc/mounts.
Bonus: fun facts
- Nested claudepods are supported up to half of kernel userns nesting limit. To avoid kernel overlayfs nesting limits, each level's Nix store is a standalone overlay listing all parents as lowerdir layers.
- systemd is actively hostile to fast startup and requires workarounds
- SYSTEMD_DEFAULT_MOUNT_RATE_LIMIT_BURST=1000. Otherwise, systemd mounts a lot of file systems, notices the mounts came in faster than 5/s and stalls boot.
- Static /etc/machine-id to avoid a ~1 s stall on fsync after writing a new ID.