blaude

Run Claude Code in a bubblewrap sandbox for security isolation.

Why?

Claude Code with --dangerously-skip-permissions can execute arbitrary commands. blaude wraps it in a Linux sandbox that:

• Isolates filesystem access (project directory, config, and caches writable; system directories read-only)
• Drops all Linux capabilities
• Uses separate namespaces (PID, IPC, UTS, user)
• Sanitizes environment variables
• Optionally disables network access

Installation

# Install bubblewrap
sudo apt install bubblewrap  # Debian/Ubuntu
sudo dnf install bubblewrap  # Fedora/RHEL

# Install blaude
curl -o ~/.local/bin/blaude https://raw.githubusercontent.com/c0ffee0wl/blaude/main/blaude
chmod +x ~/.local/bin/blaude

Requires Claude Code installed and in PATH.

Drop-in Replacement

blaude is a drop-in replacement for claude. All arguments not recognized by blaude are passed directly to the Claude Code CLI:

# These are equivalent (but blaude runs in a sandbox)
claude -p "hello"
blaude -p "hello"

claude --resume
blaude --resume

claude mcp list
blaude mcp list

To always run Claude Code in a sandbox, add an alias to your shell config:

# Add to ~/.bashrc or ~/.zshrc
alias claude=blaude

Commands that need to modify system files automatically bypass the sandbox:

Command	Reason
update	Updates claude binary in ~/.local/bin
install	Installs shell integration
install-github-app	Configures GitHub integration

Usage

# Run Claude Code in sandbox (current directory)
blaude

# Pass any claude options directly
blaude -p "explain this codebase"    # prompt mode
blaude -c                            # continue conversation
blaude -v                            # show claude version
blaude --resume                      # resume picker
blaude mcp list                      # MCP commands

# Mount additional directories
blaude -m ~/shared-libs              # read-only
blaude -m ~/shared-libs:rw           # read-write

# Enable git commits from sandbox
blaude --git

# Enable SSH for GitHub auth
blaude --ssh

# Disable network access
blaude --no-network

# Run isolated (no workspace, workdir /tmp)
blaude --tmp

# Mix blaude and claude options freely
blaude --git --ssh -c
blaude -c --git --ssh

# Run different command in sandbox
blaude --exec bash

Options

Option	Description
--env KEY=VALUE	Set environment variable in sandbox
-m, --mount PATH	Mount directory (append :rw for read-write)
--git	Mount git config and pass GH_TOKEN/GITHUB_TOKEN
--ssh	Mount SSH keys and forward agent
--no-network	Disable network access
--keyring	Enable GNOME Keyring access (for keytar)
--chic	Run claudechic TUI instead of claude
--tmp	Run isolated in /tmp
--clear-tmp	Use empty tmpfs for /tmp instead of mounting host's /tmp
--debug	Show bwrap command before executing
--dry-run	Show command without executing
--exec CMD	Run CMD instead of claude

All other options (like -p, -c, -v, --resume, etc.) pass directly to claude.

What's Mounted

Path	Access	Purpose
/usr, /lib*, /bin, /etc	read-only	System binaries and libraries
/tmp	read-write	Host's /tmp (use --clear-tmp for isolated tmpfs)
/workspaces/<dir>	read-write	Your project (current directory)
~/.claude	read-write	Claude Code config (includes claudechic config)
~/.config/	read-write	User config (uv, fabric, google-chrome, etc.)
~/.notebooklm-mcp/	read-write	notebooklm-mcp auth and Chrome profile
~/.claude-mem/	read-write	Persistent memory across sessions
~/.bun/	read-only	Bun runtime and packages (~/.bun/bin in PATH)
~/.local/bin, ~/.local/share/claude	read-only	Claude binary and data
~/.cache, ~/go, ~/.cargo, ~/.npm	ephemeral	Package manager caches (cleared on exit)

MCP Server Token Storage

MCP servers like ms-365-mcp need to persist authentication tokens. blaude handles this automatically:

• npm-linked packages: Token files (.token-cache.json, .selected-account.json) at package root are mounted read-write
• By default: D-Bus/keytar disabled, forcing file-based storage (more reliable in containers)
• With --keyring: Enables GNOME Keyring access for keytar-based storage

If you have GNOME Keyring properly configured (unlocked at login), use --keyring for secure credential storage.

claudechic Support

claudechic is a Python-based TUI wrapper for Claude Code. Use --chic to run it inside the sandbox:

blaude --chic              # Run claudechic in sandbox
blaude --chic -c           # Continue conversation via claudechic

Config file (~/.claude/.claudechic.yaml) is writable via the ~/.claude mount.

User Config Directory

The entire ~/.config/ directory is mounted read-write if it exists. This includes:

• uv config (~/.config/uv/uv.toml) - Python preference settings (e.g., python-preference = "system")
• Fabric (~/.config/fabric/) - Patterns, sessions, contexts, strategies, extensions, OAuth tokens, .env
• Google Chrome (~/.config/google-chrome/) - Browser profile for automation (Puppeteer, Playwright, OAuth flows)
• Other tool configurations as needed

# Setup fabric outside sandbox first
fabric --setup

# Then use normally inside sandbox
blaude --exec fabric -p "summarize"

notebooklm-mcp Support

notebooklm-mcp is an MCP server for NotebookLM. blaude automatically mounts ~/.notebooklm-mcp/ for auth persistence:

# Authenticate outside sandbox first (requires browser)
notebooklm-mcp-auth

# Then use normally - MCP server reads cached tokens inside sandbox
blaude

The directory stores auth.json (cookies/CSRF/session) and chrome-profile/ for automatic re-authentication.

Environment Variables

All Claude Code environment variables are automatically passed through if set:

Category	Variables
Authentication	ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL, ANTHROPIC_CUSTOM_HEADERS, ANTHROPIC_FOUNDRY_*, AWS_BEARER_TOKEN_BEDROCK
Model Config	ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_*_MODEL, CLAUDE_CODE_SUBAGENT_MODEL, CLAUDE_CODE_EFFORT_LEVEL, MAX_THINKING_TOKENS, VERTEX_REGION_*
Bash/Commands	BASH_DEFAULT_TIMEOUT_MS, BASH_MAX_*, CLAUDE_CODE_SHELL, CLAUDE_CODE_SHELL_PREFIX, CLAUDE_CODE_DISABLE_BACKGROUND_TASKS
Token Limits	CLAUDE_CODE_MAX_OUTPUT_TOKENS, CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS, MAX_MCP_OUTPUT_TOKENS
Cloud Providers	CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX, CLAUDE_CODE_USE_FOUNDRY, CLAUDE_CODE_SKIP_*_AUTH, AWS_*
MCP	MCP_TIMEOUT, MCP_TOOL_TIMEOUT, MCP_OAUTH_CALLBACK_PORT, MCP_CLIENT_SECRET, ENABLE_TOOL_SEARCH
UI/Display	CLAUDE_CODE_HIDE_ACCOUNT_INFO, CLAUDE_CODE_DISABLE_TERMINAL_TITLE, IS_DEMO, DISABLE_COST_WARNINGS
Memory	CLAUDE_CODE_DISABLE_AUTO_MEMORY
Features	CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS, CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION, CLAUDE_CODE_ENABLE_TASKS, CLAUDE_CODE_PLAN_MODE_REQUIRED, CLAUDE_CODE_TEAM_NAME, CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS
Telemetry	CLAUDE_CODE_ENABLE_TELEMETRY, OTEL_METRICS_EXPORTER
Advanced	CLAUDE_AUTOCOMPACT_PCT_OVERRIDE, DISABLE_PROMPT_CACHING*, SLASH_COMMAND_TOOL_CHAR_BUDGET, CLAUDE_CODE_ADD_DIRECTORIES_CLAUDE_MD
Proxy	HTTP_PROXY, HTTPS_PROXY, NO_PROXY, CLAUDE_CODE_PROXY_RESOLVES_HOSTS
GitHub (requires --git)	GH_TOKEN, GITHUB_TOKEN
Other LLM APIs	OPENAI_API_KEY, AZURE_OPENAI_*, GOOGLE_API_KEY, GEMINI_API_KEY, MISTRAL_API_KEY, XAI_API_KEY, JINA_API_KEY, etc.
claudechic	CLAUDECHIC_DEBUG, CLAUDECHIC_REMOTE_PORT, CHIC_PROFILE, CHIC_SAMPLE_THRESHOLD
notebooklm-mcp	NOTEBOOKLM_COOKIES, NOTEBOOKLM_CSRF_TOKEN, NOTEBOOKLM_SESSION_ID, NOTEBOOKLM_MCP_*
Webhooks	Any variable ending in _WEBHOOK (e.g., SLACK_WEBHOOK, DISCORD_WEBHOOK)
Webshare	Any variable starting with WEBSHARE_ (e.g., WEBSHARE_API_KEY, WEBSHARE_PROXY)

Use --env KEY=VALUE to pass additional variables not in this list.

License

GPL-3.0