litterbox

Overview

litterbox is an open-source CLI tool written in Rust that creates sandboxed development environments using Podman containers on Linux. Unlike most agent sandbox tools that focus on headless CLI execution, litterbox forwards your Wayland display socket into the container — so you can run your full GUI development environment (editor, browser, AI agents) inside the sandbox.

The name is a cat pun, and the philosophy matches: this is a contained environment where things might get messy, but at least the mess stays in the box. The tagline — "Somewhat Isolated Development Environments" — sets expectations honestly from the start.

How It Works

When you set up a litterbox environment, the workflow is:

1. Define — litterbox define myproject creates a Dockerfile from an opinionated template in ~/Litterbox/definitions
2. Build — litterbox build myproject builds the container image and prompts you for configuration options (which access to grant, which SSH keys to expose)
3. Start — litterbox start myproject launches the container with your project directory mounted

The container gets access to exactly one folder on your host filesystem — your project directory. Nothing above it, nothing beside it. Your home directory, SSH keys, dotfiles, and everything else stays on the host.

Wayland socket forwarding means applications inside the container render natively on your desktop. You're not SSH-ing into a headless box — you're running a full graphical environment that happens to be containerized. This makes litterbox feel less like a sandbox and more like a parallel desktop.

The tool also supports PipeWire forwarding for audio (with explicit security warnings), device passthrough, and uses Landlock LSM on supported kernels for additional filesystem restrictions.

SSH Agent

The standout feature is litterbox's custom SSH agent, powered by the russh Rust library.

Instead of forwarding your entire SSH agent socket (which gives the container access to all your keys), litterbox runs its own agent that:

• Exposes only selected keys — during setup, you choose which SSH keys each litterbox can see
• Prompts before signing — every time something inside the container tries to use an SSH key, a pop-up window appears on your host asking for confirmation

This is a meaningful improvement over the typical container SSH approach. Most sandboxing tools either forward the full agent (exposing everything) or don't forward at all (breaking git operations). litterbox's per-key, per-operation confirmation hits a sweet spot — the container can do git push, but only with keys you've approved, and only when you click "yes" on a pop-up.

The tradeoff is friction. If you're running an AI agent that makes frequent git operations, those confirmation pop-ups could get annoying fast. But for the supply chain attack threat model, that friction is the feature.

Security Model

litterbox's security model is best described as "honest pragmatism." The README contains one of the most thorough security disclaimers in the open-source sandbox space:

What's protected:

• Home directory and filesystem (container restricted to one folder)
• SSH keys (custom agent with per-key access and signing confirmation)
• Other projects on the machine

What's explicitly NOT protected (per the README):

• Shared kernel — container processes run on your host kernel. Kernel exploits escape the sandbox.
• Wayland access — the container has full access to your Wayland server, including your clipboard. Don't copy passwords while a litterbox is running.
• PipeWire access (if enabled) — the container can record your microphone and play audio through your speakers.
• Podman vulnerabilities — container runtime bugs could allow escape.
• Network — only limited network isolation by default.
• Device access — any exposed device is fully accessible inside the container.

The README also acknowledges that litterbox itself has many external Rust dependencies, making it vulnerable to the very supply chain attacks it aims to mitigate. A stated long-term goal is reducing dependencies to a minimum.

This level of honesty is rare. Most sandbox tools emphasize what they protect; litterbox leads with what it doesn't.

Strengths

• Novel SSH agent — per-key exposure with user confirmation pop-ups is a genuinely unique approach to credential protection in containers
• GUI-native sandboxing — Wayland forwarding means you run real desktop environments inside the sandbox, not just CLIs
• Radical honesty — the security disclaimers set appropriate expectations instead of overselling isolation
• Landlock integration — uses Linux Security Module features when available for filesystem restrictions beyond basic container isolation
• Static binary — minimal shared library dependencies, easy to install on any Linux distro with Podman
• Repeatable environments — Dockerfile-based definitions serve as documentation for your dev setup

Weaknesses

• Linux-only — no macOS, no Windows. Requires Podman specifically (not Docker). This eliminates the majority of developers.
• Small community — 66 stars and 6 forks suggests early-stage adoption. Limited community support if things break.
• Wayland-only — no X11 support. While Wayland is the future, many Linux developers still run X11.
• Clipboard leakage — Wayland socket access means the container can read your clipboard. This is a fundamental architectural limitation, not a bug.
• Manual setup — define, build, configure SSH keys, start. More ceremony than yolobox claude or shai claude.
• No agent-specific tooling — unlike yolobox (which pre-aliases agent CLIs) or shai (which wraps agent commands), litterbox is a general-purpose dev sandbox that happens to work for agent isolation.

Bottom Line

litterbox occupies a unique niche in the sandbox landscape: it's the only tool focused on full GUI development environments inside containers, rather than headless agent execution. The Wayland forwarding and custom SSH agent are genuinely differentiated features that no competitor offers.

The tradeoff is accessibility. Linux-only, Podman-only, Wayland-only narrows the audience dramatically. And the manual setup process means this is a tool for developers who are willing to invest time in configuring their sandbox correctly — not for someone who wants to type one command and go.

The honest security disclaimers reveal a mature understanding of threat modeling. litterbox doesn't pretend containers are VMs. It targets supply chain attacks — the scenario where trusted code gets compromised — and provides "better than nothing" isolation for that specific threat. In a space full of tools that oversell their security properties, that honesty is worth something.

For Linux developers who want to run their full dev environment (editor, agents, browser) inside a sandbox with SSH key protection, litterbox is the only game in town. For everyone else, the platform constraints are a dealbreaker.