convez.ai
Agente
xzrq-net

claudepod

xzrq-net/claudepod

Ver no GitHub
InicialPluginScore · de 0 a 100

Nix Home Manager module that builds and runs a tiny container to isolate coding agents

Instalação

$npx convez-ai xzrq-net/claudepod

1 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

Estrelas
1
Forks
0
Acompanhando
0
Saúde
37%
Último commit
há 2 meses
Versão
—
Issues abertas
0
Contribuidores
1

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 .claude and .codex) and host ~/src are 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/store mount.
  • 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/store path 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.
Ver o original no GitHub

Bom para

Relacionados