convez.ai
AgenteDevOps & InfraestruturaIntermediário
faern

Agent Sandbox

faern/agent-sandbox

Sandbox podman rootless para agentes de código IA com isolamento controlado

Ver no GitHub
InicialPluginScore · de 0 a 100

Isolamento seguro para agentes de código IA (Claude Code, OpenCode, Mistral Vibe) em contêineres rootless Podman. Previne acesso não autorizado ao sistema de arquivos do host enquanto mantém compatibilidade de caminhos e propriedade de arquivos, ideal para executar agentes com segurança em ambientes Linux.

Instalação

$npx convez-ai faern/agent-sandbox

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
3
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Executar Claude Code em contêiner isolado sem risco ao sistema
  • Permitir automação de código IA com boundary de segurança definido
  • Desenvolvimento seguro com agentes OpenCode e Mistral Vibe

Veredito

Solução pragmática e minimalista para isolamento de agentes IA em Linux. Focada em segurança sem overhead operacional, ideal para equipes que precisam de boundary claro entre agentes e infraestrutura host.

README

A tradução para o português deste README ainda está na fila.

agent-sandbox

Run AI coding agents inside rootless podman containers. Supports Claude Code, OpenCode, and Mistral Vibe. Isolates the agent from your system — the host filesystem is not accessible except for a small set of controlled mounts. Currently only designed for being used on a Linux host.

The sandbox gets a user with the same username and home dir as on your host. The container then runs with --userns=keep-id so file ownership matches the host. The intention is that all file paths inside the container should match the host. This makes all absolute and relative paths written to files match inside and outside the sandbox for a smoother experience.

This is not an AI agent session manager or git worktree manager. Nor does it come bundled with skills or anything else that will get old in a week. All it does is help you isolate the agent in a container to prevent it from accessing most of your host system, or messing up files outside your project working directory.

agent-sandbox does not come with any prebuilt container images. Instead the script builds an image on demand when executed. The default image is based on Ubuntu and includes standard development tools (compilers, version control, search utilities, etc.). The container definition is configurable both globally and per project (working directory).

How it works

agent-sandbox is a single script. It is invoked via symlinks named claude-sandbox, opencode-sandbox, and vibe-sandbox. The script detects which agent to use based on the name it was invoked as. Each agent gets its own config paths, environment variables, and install method.

Sandbox boundary

The container runs as a rootless podman container with no access to the host filesystem beyond a controlled set of mounts:

WhatModeNotes
Project directory ($PWD)read-writeRead-only with --read-only. Omitted with --stateless.
Agent configread-writeEphemeral copy per session — changes don't affect the host (see below). Conversations are the exception (see next row).
~/.gitconfigread-onlyDisable with --no-gitconfig. Git credentials and SSH/GPG keys are not mounted.
Agent binaryread-onlyOnly with --agent host (default).
Repository .git dirread-writeControlled by --git. Default rw (ro with --read-only, omitted with --stateless or --git none). At repo root, .git is inside the project mount.
Claude project conversationsread-write~/.claude/projects/<project>/ mounted directly from host so conversations persist across sessions. Omitted with --stateless.
Claude credentialsread-write~/.claude/.credentials.json mounted directly from host so OAuth token refreshes persist.
Extra host paths (--volume)read-writeOpt-in. Mounted at the same absolute path inside the container. :ro for read-only. Repeatable.

Agent config files are copied into an ephemeral directory per session:

AgentConfigs copied
Claude Code~/.claude.json, ~/.claude/
OpenCode$XDG_CONFIG_HOME/opencode/, ~/.local/share/opencode/

This means the agent is directly logged in and has your settings. Depending on your threat model this can be a risk.

Additional hardening:

  • Runs rootless with --userns=keep-id (no host root privileges)
  • Sensitive /proc paths are masked (kcore, kallsyms, config.gz, etc.)
  • Host processes are hidden (hidepid=2)
  • The script warns and prompts for confirmation if run from $HOME or outside $HOME

SELinux labels

On SELinux hosts the container runs with --security-opt label=disable, so SELinux type-enforcement is not applied to the bind mounts. This is deliberate: with podman's :z relabeling, only files present at container start get a label the container can read. Files added to a mount mid-session keep their original host label (mv, cp -a, and rsync all preserve it), and a confined container then cannot read them. Disabling labels lets the agent read anything dropped into a mount by any method, and avoids mutating host SELinux labels. Isolation still rests on rootless execution, the user namespace, and the limited set of bind mounts - SELinux was only ever a defense-in-depth layer on top of those. No effect on hosts without SELinux.

Agent binary

By default the host's agent binary is bind-mounted into the container. This keeps the container image small and lets you get updates without rebuilding. This is configurable with --agent:

  • --agent host (default) — Mount the host binary read-only. If the binary is not found on the host, falls back to install automatically. Note: Not supported for Mistral Vibe.
  • --agent install — Install the agent into the container image during build (runs the agent's official install script as the sandbox user). Required for Mistral Vibe.
  • --agent none — Don't provide the agent at all. Use this when your custom containerfile installs it.

Requirements

  • Podman (rootless)
  • The agent installed on the host (unless using --agent install or --agent none)
  • fzf (only for --cleanup)

Install

This is just a standalone bash script. Copy or symlink it somewhere in your PATH.

cp agent-sandbox ~/.local/bin/
ln -s agent-sandbox ~/.local/bin/claude-sandbox
ln -s agent-sandbox ~/.local/bin/opencode-sandbox
ln -s agent-sandbox ~/.local/bin/vibe-sandbox

Usage

Invoke as claude-sandbox, opencode-sandbox, or vibe-sandbox. All examples below use claude-sandbox but opencode-sandbox and vibe-sandbox work identically.

# Start the agent in the sandbox, with the current working directory
# read-write mounted in the container
claude-sandbox

# Read-only project mount
claude-sandbox --read-only

# No project mount at all — pure chat
claude-sandbox --stateless

# Force image rebuild
claude-sandbox --rebuild

# Drop into a shell inside the sandbox instead of starting the agent directly
claude-sandbox --shell

# Pass args to the agent after a double dash (--)
claude-sandbox -- --model sonnet -p "explain this repo"

# Mount extra host directories at the same path inside the container.
# Relative paths resolve against $PWD. Repeatable. Add :ro for read-only.
claude-sandbox --volume ../sibling-repo
claude-sandbox --volume /shared/data:ro --volume ~/notes

# Pass extra arguments to podman run
claude-sandbox --podman-arg --network=host
claude-sandbox --podman-arg --cap-add=NET_RAW
# For mounts where host and container paths differ, use --podman-arg directly:
claude-sandbox --podman-arg --volume=/host/path:/sandbox/path:ro

# List and remove old images
claude-sandbox --cleanup

# Install the agent into the image during build
claude-sandbox --agent install

# Skip host binary mount (use when containerfile installs the agent)
claude-sandbox --agent none

# Note: Mistral Vibe requires --agent install as it cannot be mounted from host
vibe-sandbox --agent install

# Work in a git worktree for a specific branch
claude-sandbox --worktree feature-branch

# Pass through /dev/kvm for running VMs inside the sandbox
claude-sandbox --kvm

# Don't mount ~/.gitconfig into the container
claude-sandbox --no-gitconfig

# Mount .git read-only (git log/diff works, but no commits)
claude-sandbox --git ro

# No .git access at all
claude-sandbox --git none

# Skip agent permission prompts (claude-sandbox only)
claude-sandbox --yolo

# Verbose output from the sandbox setup
claude-sandbox -v

Custom containers

Place a Containerfile.agent in your project root, or globally in $XDG_CONFIG_HOME/agent-sandbox/ (defaults to ~/.config/agent-sandbox/). Project containerfiles override the global one.

Project configs require trust approval on first use and after any change. This protects it from being poisoned by the container, since it is available with write permissions inside the sandbox.

The file must include a FROM line. The script splits your file at the first FROM line and injects its own instructions into the final Containerfile. The resulting build order is:

─── Your FROM line ───────────────────────────────────────────
INJECTED: ARG USERNAME, USER_HOME, USER_UID, USER_GID
INJECTED: User creation (matching host UID/GID)
INJECTED: mkdir ~/.local, ~/.local/{bin,share}, ~/.config (owned by user)
INJECTED: ENV PATH (prepends ${USER_HOME}/.local/bin)
─── Rest of your containerfile ───────────────────────────────
INJECTED: USER root (reset after your containerfile)
INJECTED: Sudo setup (if sudo is installed)
INJECTED: USER ${USERNAME}
INJECTED: Agent install (only with --agent install)

Since the sandbox user and ARGs are injected before the rest of your file, you can freely use USER ${USERNAME} to run commands as the sandbox user, then switch back with USER root as needed.

The following ARGs are available directly in your containerfile (no need to declare them):

  • USERNAME — host username
  • USER_HOME — host home directory path
  • USER_UID — host user ID
  • USER_GID — host group ID

Images are tagged by config content hash — different configs produce separate images that rebuild automatically when the config changes.

Example: Fedora + Rust

Containerfile.agent:

FROM fedora:latest

RUN dnf install -y git curl ripgrep fd-find jq gcc sudo \
    && dnf clean all

# Install Rust as the sandbox user — no chown needed
USER ${USERNAME}
RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y \
    --default-toolchain stable --component rust-analyzer
ENV PATH="${USER_HOME}/.cargo/bin:${PATH}"

Example: Ubuntu + Node.js

Containerfile.agent:

FROM ubuntu:24.04

RUN apt-get update \
    && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
        git curl ca-certificates ripgrep fd-find jq build-essential sudo \
    && rm -rf /var/lib/apt/lists/*

# Install Node.js via NodeSource
RUN curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
    && apt-get install -y nodejs \
    && rm -rf /var/lib/apt/lists/*

Environment variables

AgentForwarded env vars
Claude CodeANTHROPIC_*
OpenCodeANTHROPIC_*, OPENAI_*, GEMINI_*, GROQ_*, AWS_*, AZURE_*, OPENCODE_*, GOOGLE_*, GITLAB_*, CLOUDFLARE_*, GITHUB_TOKEN
  • SANDBOX_CONTAINERFILE — override containerfile path (must exist, skips discovery)

Runtime env file

Place a sandbox.env in $XDG_CONFIG_HOME/agent-sandbox/ (defaults to ~/.config/agent-sandbox/sandbox.env) to pass extra environment variables into the container at runtime. This is useful for tokens or credentials that should not be baked into the image.

The file uses podman's native --env-file format:

# API tokens
GH_TOKEN=github_pat_xxxxxxxxxxxx

# Pass through from host environment (no value — uses host's value)
SOME_HOST_VAR

License

This project is licensed under the GNU General Public License v3.0 or later.

Ver o original no GitHub

Bom para

Relacionados