Skip to content

About

Providing a strong Gravity (sandbox) in the wild world of AI Agents (Antigravity, claude code, ...), to preserve the developer's Sanity.

Topics

Resources

Contributing

Security policy

Stars

45 stars

Watchers

1 watching

Forks

Repository files navigation

Sanity-Gravity: The Antigravity Sandbox

Sanity-Gravity Logo

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

English | 繁體中文 | 日本語

CI License

Why a sandbox?

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.

AI agent reporting it deleted the entire project directory AI agent escalating: entire Windows user profile wiped, 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.

Prerequisites

  • Docker & Docker Compose (v2.0+)
  • Python 3.11+
  • 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. Running multiple sandboxes: the host's fs.inotify.max_user_instances (often 128 by default) can run out when several sandboxes are up at once, surfacing as inotify_init() failed / EMFILE errors in Chrome, dsh, or IDE language servers inside the containers; fix it on the host with sudo sysctl fs.inotify.max_user_instances=1024 and persist it via a file under /etc/sysctl.d/.

TL;DR

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

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.

Feature Description
Host Isolation Even if an agent runs rm -rf / or downloads malware, only the sandbox is destroyed. Your host stays untouched.
Full GUI Desktop Ubuntu 24.04 + XFCE4 + KasmVNC. Agents operate browsers and GUI apps just like a human would.
Headless CLI Agents Minimal images for Gemini CLI, Claude Code, OpenAI Codex, OpenCode, and DeepSeek Harness - no desktop overhead, just SSH.
Out-of-the-Box Pre-installed with Antigravity IDE and Git; every desktop variant also ships a browser (Chrome on amd64, Chromium on arm64). Zero setup time.
Seamless Disk I/O Smart UID/GID mapping. No root-owned file disasters after host volume mounts.
Multi-Instance Parallel isolated sandboxes. Host ports are auto-allocated when unspecified (zero conflicts), or can be set manually.
Container Snapshots Freeze your configured environment (installed software, active logins) into a new image branch.
Verified IDE Updates ide update fetches the current Antigravity IDE and agy builds from Google and checks each against the checksum Google publishes before replacing the installed one.
SSH Agent Proxy Use host SSH keys inside containers — no private key copying required.
Multi-Arch All images support both amd64 and arm64.

📺 Watch Demo on YouTube

Choose Your Sandbox

Every image is described by a tag: {agent}-{desktop}-{connector}[-{base}], where the base is left out for the default ubuntu (e.g. cc-none-ssh, or cc-none-ssh-debian on Debian 12). Pick one that matches your use case:

I want to... Tag Connect via
Run Antigravity IDE in browser ag-xfce-kasm https://localhost:8444
Run Antigravity IDE via VNC ag-xfce-vnc localhost:5901
Use Gemini CLI in a terminal gc-none-ssh ssh -p 2222 ...
Use Gemini CLI with a desktop gc-xfce-kasm https://localhost:8444
Use Claude Code in a terminal cc-none-ssh ssh -p 2222 ...
Use Claude Code with a desktop cc-xfce-kasm https://localhost:8444
Use OpenAI Codex in a terminal cx-none-ssh ssh -p 2222 ...
Use OpenAI Codex with a desktop cx-xfce-kasm https://localhost:8444
Use OpenCode in a terminal oc-none-ssh ssh -p 2222 ...
Use OpenCode with a desktop oc-xfce-kasm https://localhost:8444
Use OpenCode Desktop in browser ocd-xfce-kasm * https://localhost:8444
Use DeepSeek Harness in a terminal dsh-none-ssh * ssh -p 2222 ...
Use DeepSeek Harness with a desktop dsh-xfce-kasm * https://localhost:8444
Swap XFCE for the LXQt desktop cc-lxqt-kasm * https://localhost:8444
Use a minimal desktop instead cc-openbox-kasm * https://localhost:8444

* Community tier: build locally with ./sanity-cli build <tag>; not published to GHCR, so pull has nothing to fetch.

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 78 valid combinations per base, 156 in total. See Modular Tag System for the full matrix, dimension model, and constraint rules.

Missing your favorite agent? Adding one takes a manifest plus a Dockerfile - see Bring Your Own Agent.

Command Reference

Lifecycle

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

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

ag installs the Antigravity IDE from Google's official tarball, pinned by version and build id and verified against the sha256 Google publishes for it. Auto-update is off, so a sandbox stays on the build it was built with until you ask for another one. The Agent Manager's backend is agy, a separate CLI the IDE would otherwise download and update on its own; the image installs a pinned agy, verified against the sha512 Google publishes, and keeps the IDE from replacing it. ide update moves the IDE and agy together.

  • Host side: sanity-cli manages container lifecycles. Maintenance commands auto-inject the latest gravity-cli into the target container first, so a container built from an older checkout still runs the current installer.
  • Container side: gravity-cli asks Google's updaters which IDE and agy builds are current, downloads them, checks each against the checksum Google publishes for that build, and swaps them in. It is the same script the image build runs, so the sandbox wrapper and the desktop entries have one source.

From the Host

# Download, verify and install the current IDE build
./sanity-cli ide update --name sanity-gravity

# Same, plus a clear-out of the Electron caches that outlive a version change
./sanity-cli ide reinstall --name sanity-gravity

Inside the Container

sudo gravity-cli ide update
sudo gravity-cli 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 shared by every base image: SSH + supervisord
│   └── rootfs/                 # Shared overlay (entrypoint, supervisor configs)
├── plugins/                    # Manifest-driven plugins
│   ├── base-images/            #   ubuntu, debian
│   ├── desktops/               #   xfce, lxqt, openbox, none
│   ├── agents/                 #   ag (Antigravity), agy (Antigravity CLI), gc (Gemini CLI), cc (Claude Code), cx (OpenAI Codex), oc (OpenCode), ocd (OpenCode Desktop), dsh (DeepSeek Harness)
│   └── connectors/             #   kasm (KasmVNC), vnc (TigerVNC), ssh
├── 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

About

Providing a strong Gravity (sandbox) in the wild world of AI Agents (Antigravity, claude code, ...), to preserve the developer's Sanity.

Topics

Resources

Contributing

Security policy

Stars

45 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages