A containerized sandbox for Agentic AI — full desktop, headless CLI, or SSH-only, in seconds.

English | 繁體中文 | 日本語

An AI coding agent was asked to reorganize a project. Instead it ran a recursive force-delete against the wrong path — because the developer's Windows username had a space in it — and wiped their entire user profile, bypassing the Recycle Bin.

This isn't hypothetical — it happened to one of this project's own contributors. The trigger was Windows-specific; the risk isn't.

Agentic coding tools — Antigravity, Claude Code, Codex — are at their best when you let them run autonomously: plan, edit, run commands, no babysitting. But "autonomous" + "your real filesystem" is russian roulette. One malformed path, one over-eager sub-agent, and there is no undo.

sanity-gravity is the seatbelt. It hands the agent a full Linux desktop / IDE / SSH box to run wild in, while your real machine stays untouchable:

• Isolated filesystem — the agent can't see your host unless you explicitly mount a workspace.
• Least privilege — dropped Linux capabilities, pid limits, no core dumps.
• Runs where you work — Linux, macOS (Apple Silicon), and Windows (WSL2).
• Snapshots — broke the environment? roll back in seconds.

Let the agent go full YOLO. The blast radius stops at the container wall.

• Docker & Docker Compose (v2.0+)
• Python 3.7+
• Tested on: Ubuntu (amd64/arm64), macOS (Apple Silicon), Windows (WSL2 + Docker Desktop)

Windows / WSL2: run scripts/setup-wsl-crashdump-policy.ps1 once to stop WSL from writing gigabyte crash dumps when a sandboxed browser/agent segfaults.

# 1. Clone
git clone https://github.com/shiritai/sanity-gravity.git
cd sanity-gravity

# 2. (Optional) Build locally instead of pulling from GHCR
# ./sanity-cli build

# 3. Launch the sandbox (Auto-pulls missing images from GHCR!)
./sanity-cli up -v ag-xfce-kasm --password mysecret

Open https://localhost:8444 — your sandboxed desktop is ready!

• Username: your host OS username
• Password: mysecret (default: antigravity)

The self-signed certificate warning on localhost is expected. Click through it.

AI agents run arbitrary code. One rogue rm -rf / and your host is toast. Sanity-Gravity confines every agent action inside a disposable Docker container while streaming a full desktop experience to your browser — or providing just a minimal SSH shell when that's all you need.

📺 Watch Demo on YouTube

Every image is described by a tag: {agent}-{desktop}-{connector}. Pick one that matches your use case:

First time? Start with ag-xfce-kasm — it gives you the full desktop experience via your browser.

Heads-up: gc (Gemini CLI) lost its free tier on 2026-06-18 and now requires a paid Gemini API key / Code Assist license. New users should prefer agy (Antigravity CLI), Google's official successor — already shipped here.

There are 19 valid combinations in total. See Modular Tag System for the full matrix, dimension model, and constraint rules.

For a detailed explanation of persistence, isolation, and state management, see the Sandbox Lifecycle Guide.

./sanity-cli up -v <tag>        # Start a sandbox
  --password <pwd>              #   SSH/VNC password (default: antigravity)
  --workspace <path>            #   Host directory to mount (default: ./workspace)
  --name <name>                 #   Project name for multi-instance (default: sanity-gravity)
  --cpus <n> --memory <n>       #   Resource limits (e.g. --cpus 2 --memory 4G)
  --image <img>                 #   Use a snapshot image instead of the default

./sanity-cli down               # Stop and remove containers
./sanity-cli stop / start       # Pause / resume
./sanity-cli restart            # Force restart
./sanity-cli clean              # Deep cleanup: containers, volumes, and local images

./sanity-cli status             # Show running instances
./sanity-cli shell              # Drop into container shell (zsh, fallback to bash)
  --use {zsh,bash}              #   Pick shell explicitly (disables fallback)
./sanity-cli open               # Open web desktop in browser

./sanity-cli build [tag...]     # Build images (default: all)
  --no-cache                    #   Disable Docker layer cache
./sanity-cli list               # Show all valid tags
./sanity-cli list --json        # JSON output (for CI matrix)
./sanity-cli check              # Verify Docker prerequisites

Full reference with all flags and environment variables: CLI Reference

Sanity-Gravity provides a robust defense mechanism against accidental IDE or browser uninstallation caused by apt upgrade.

• Host side: sanity-cli manages container lifecycles. Maintenance commands auto-inject the latest protection script into the target container, ensuring backward compatibility with legacy snapshots.
• Container side: gravity-cli (built-in) safely manages Antigravity IDE and Google Chrome via dpkg-divert, guaranteeing their --no-sandbox privilege protections survive system updates.

# Safely update IDE to the latest package version
./sanity-cli ide update --name sanity-gravity

# Nuclear option: full wipe + clean reinstall to fix persistent crashes
./sanity-cli ide reinstall --name sanity-gravity

sudo gravity-cli update-ide     # Equivalent to 'ide update'
sudo gravity-cli reinstall-ide  # Equivalent to 'ide reinstall'

A built-in proxy bridges your host's SSH Agent Socket into the container. This enables git push / git pull inside the sandbox using your host's private keys — without ever copying them.

./sanity-cli up handles this automatically. For manual control:

./sanity-cli proxy status       # Check proxy and active connections
./sanity-cli proxy setup        # Restart / fix proxy
./sanity-cli proxy remove       # Terminate proxy

Run unlimited parallel sandboxes using --name:

# Launch a second instance
./sanity-cli up -v ag-xfce-kasm --name dev-02 --workspace /tmp/dev02

Zero-Conflict Guarantee: sanity-cli auto-allocates free host ports when using a custom name. Check your assigned ports via ./sanity-cli status. Target a specific instance with --name (e.g. ./sanity-cli down --name dev-02).

Freeze your configured environment — installed software, login sessions, custom settings — into a reusable image.

1. Create a snapshot:

   ./sanity-cli snapshot --name my-base-env --tag my-verified-state:v1

2. Launch from the snapshot:

   ./sanity-cli up -v ag-xfce-kasm --name new-experiment --image my-verified-state:v1

All images — including GUI variants — expose SSH on port 2222 by default. This enables:

• Headless automation — script tasks from the host without opening a desktop
• Port forwarding — ssh -L 3000:localhost:3000 -p 2222 $USER@localhost
• Remote development — VS Code Remote SSH, JetBrains Gateway

ssh -p 2222 $USER@localhost

sanity-gravity/
├── sanity-cli                  # CLI entry point (Python 3, no external deps)
├── sandbox/
│   ├── Dockerfile.base         # Base layer: Ubuntu 24.04 + SSH + supervisord
│   ├── layers/
│   │   ├── desktops/           # xfce, none
│   │   ├── agents/             # ag (Antigravity), agy (Antigravity CLI), gc (Gemini CLI), cc (Claude Code), cx (OpenAI Codex)
│   │   └── connectors/         # kasm (KasmVNC), vnc (TigerVNC), ssh
│   └── rootfs/                 # Shared overlay (entrypoint, gravity-cli, supervisor configs)
├── lib/                        # Proxy manager module
├── config/                     # Runtime-generated docker-compose files (git-ignored)
├── tests/                      # Pytest integration suite
├── workspace/                  # Default bind-mounted workspace
└── .github/workflows/          # CI/CD pipelines

For details on the 4-layer FROM-chained build system and CI architecture, see Architecture and CI/CD.

"Sanity-Gravity" — providing a strong Gravity (constraints) in the unpredictable world of Antigravity (AI agents), to preserve the developer's Sanity.

By confining unvetted AI execution to disposable containers, we eliminate irreversible damage: accidental file deletion, credential hijacking, configuration pollution.

Apache License 2.0