agy-profiles

Clean-room multi-profile sandbox manager, stdio MCP server, and hardened localhost console for Google Antigravity on macOS.

Overview

Running multiple accounts, client workspaces, or untrusted repositories inside Google Antigravity Hub and Antigravity IDE risks cross-profile authentication bleed, shell login environment leakage, stale Chromium locks, and unintentional credential exposure. agy-profiles solves this through strict directory containment (0o700 / 0o600), locked .zshenv HOME rewriting, fail-closed MCP configuration sanitization, exact --user-data-dir process matching, and cryptographic CSRF/Origin isolation on its local web interface.

This repository is built purely on the Python 3 standard library (>= 3.9) with zero third-party runtime or test dependencies.

Related MCP server: local-mcp

Key Capabilities

1. Strict Sandbox Isolation: Provisions per-profile data/, ide-data/, home/, and logs/ directories under /Volumes/Dev/.antigravity-profiles (when writable on macOS, or ~/.antigravity-profiles, overridable via AGY_PROFILES_DIR or --root). Writes an immutable 0o600 .zshenv pinning HOME and ZDOTDIR inside the profile so macOS login shell environment discovery never pulls host credentials.

2. Dual Target Support (hub and ide): Launches and tracks both /Applications/Antigravity.app (Antigravity Hub) and /Applications/Antigravity IDE.app (Antigravity IDE) inside isolated --user-data-dir and --extensions-dir paths, automatically setting app_storage.json and IDE settings.json flags to disable background auto-updaters.

3. Fail-Closed Secret Sanitizer: When creating a profile with --inherit-config, copies host GEMINI.md and mcp_config.json while redacting secrets in nested env, headers, args, URL userinfo, and secret query parameters. Rejects malformed JSON instead of falling back to raw copies.

4. Symlink Allowlist and Blocklist: Rejects and strips symlinks pointing to sensitive host locations (.ssh, .gnupg, .aws, .kube, .npmrc, .netrc, .pypirc, Library/Keychains, .gemini, shell startup dotfiles). Offers conservative opt-in link policies (none, minimal, dev) for benign runtime binaries and fonts.

5. Exact Process Boundary Matching: Tracks and stops processes only when --user-data-dir=<resolved_path> matches at strict token boundaries, including descendant child processes discovered via parent-PID traversal. Escalates cleanly from SIGTERM to SIGKILL and repairs stale Chromium locks (SingletonLock, SingletonSocket, SingletonCookie, DevToolsActivePort).

6. Evidence and Obligation Ledgers: Emits structured EvidenceRecord metadata (evidence_id, authority, confidence, facts, limitations) on inspections and exposes six executable security self-checks via agy-profiles obligations.

7. Zero-Dependency Local Surfaces: Includes an argparse CLI (agy-profiles / agyp), a line-delimited JSON-RPC 2.0 stdio MCP server (agy-profiles mcp), a native macOS .app launcher compiler (agy-profiles launcher build), and an Astryx Design System Web Console (agy-profiles web) with five curated palettes (Stone, Chocolate, Gothic, Matcha, Neutral), Light and Dark modes, and self-hosted variable fonts.

Installation

Install agy-profiles and its short alias agyp into ~/.local/bin via symlink:

git clone https://github.com/harrymove-ctrl/agy-profiles.git /Volumes/Dev/agy-profiles
cd /Volumes/Dev/agy-profiles
./install.sh

Useful installer options:

./install.sh --dry-run
./install.sh --prefix ~/.local/bin --with-skill
./install.sh --uninstall

You can also run directly from the repository without modifying PATH:

./bin/agy-profiles doctor --json

Quick Start

1. Check host Antigravity bundles and sandbox health:

agy-profiles doctor

2. Verify built-in security and isolation invariants:

agy-profiles obligations

3. Create an isolated profile with minimal toolchain symlinks and sanitized host MCP config:

agy-profiles create core-research --label "Core Research" --target hub --links minimal --inherit-config

4. Launch Antigravity Hub or IDE for that profile:

agy-profiles launch core-research
agy-profiles launch core-research --target ide --workspace /Volumes/Dev/my-repo

5. Build a native Spotlight and Dock .app bundle launcher:

agy-profiles launcher build core-research --target hub

6. Open the local Web Console on 127.0.0.1:

agy-profiles web

7. Connect an AI coding client to the stdio MCP server:

{
  "mcpServers": {
    "agy-profiles": {
      "command": "agy-profiles",
      "args": ["mcp"]
    }
  }
}

Web Console and Frontend Build

The local Web Console (agy-profiles web) is built with React 19, TypeScript, @astryxdesign/core, and @stylexjs/stylex from web-ui/, then pre-compiled with Vite into src/agy_profiles/web_static/ (index.html, styles.css, app.js, mark.svg, fonts/*.woff2) so end users install and run agy-profiles with zero Node or PyPI runtime dependencies.

1. Astryx Design System & Themes: Uses the warm Stone palette by default alongside Chocolate, Gothic, Matcha, and Neutral themes, Light and Dark appearance switching, and six profile accent presets.

2. Self-Hosted Variable Typography: Bundles Fraunces Variable, Figtree Variable, and JetBrains Mono Variable .woff2 font files directly inside src/agy_profiles/web_static/fonts/ with zero external fonts.googleapis.com requests.

3. Interactive Console Workflows: Provides TopNav and SideNav switching across Profiles, Obligations, and Doctor, searchable profile table and inspector actions, a profile creation Drawer, confirmation controls, and keyboard shortcuts (/ to filter profiles, n to open Create Profile, r to refresh live state).

4. Loopback & CSP Hardening: Binds strictly to 127.0.0.1 or ::1, authenticates requests via single-use bootstrap token and X-AGY-CSRF, enforces script-src 'self' and font-src 'self', and isolates /fonts/ static serving with single-segment extension checks.

5. Rebuilding Frontend Assets (Optional Dev Only):

cd web-ui
npm install
npm run build

This updates src/agy_profiles/web_static/ directly for packaging and verification (docs/assets/web-console-overview.png).

CLI Command Reference

Verification and Testing

Run the full zero-dependency test suite across Python 3.9 and 3.14, plus the secret and contamination scanner:

python3 -m unittest discover -s tests -v
python3 scripts/check_secrets.py

Documentation

1. Architecture Overview: Five-layer clean-room module design, shell isolation rationale, and lock lifecycle.

2. Reconstruction Obligations: Live invariant definitions verified on every release.

3. Security Model: Threat model, CSP/CSRF controls, symlink jail, and fail-closed redaction guarantees.

License

MIT License. See LICENSE.