Sanity-Gravity: The Antigravity Sandbox

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

English | 繁體中文 | 日本語

Prerequisites

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

TL;DR

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

# 2. Build the images (one-time)
./sanity-cli build

# 3. Launch the recommended sandbox
./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.

Why Sanity-Gravity?

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

Choose Your Sandbox

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.

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

Command Reference

Lifecycle

./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

Inspection

./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

Build

./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

Advanced Features

IDE Management & Safe Upgrade

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.

From the Host

# 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

Inside the Container

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

SSH Agent Proxy

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

Multi-Instance

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).

Container Snapshots

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
   

SSH Access

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

Project Structure

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), gc (Gemini CLI), cc (Claude Code)
│   │   └── 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.

What's in a Name?

"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.

License

Apache License 2.0