Antigravity harness

Capability: capability:platform

Harness: Antigravity (CLI agy, App and IDE)

Antigravity is Google’s agent harness and the successor to Gemini CLI, which Google retired for individual accounts on 2026-06-18. It runs Magpie’s shared skills with repository instructions, an action guard, a terminal sandbox, and allow / ask / deny permission rules. Magpie’s secure setup for Antigravity is per user, never per repository: the sandbox, the permission rules and the guard all live in the user’s ~/.gemini/ configuration and apply to every repository the user opens. The adapter is experimental: it was validated with Antigravity CLI 1.3.6 on macOS; Linux, Windows, the App and the IDE have not been verified. The integration follows the harness contract in add-a-harness and RFC-AI-0004.

Harness contract

The shipped profile is tools/agent-isolation/antigravity/: settings.json merges into ~/.gemini/antigravity-cli/settings.json, and hooks.json merges into ~/.gemini/config/hooks.json. Those files are the profile’s source of truth; sandbox-lint derives the required ask and deny rules from the Claude Code baseline, so the two profiles cannot drift apart.

Invoke a Magpie skill

Install Magpie as an Antigravity plugin, or open a repository whose .agents/skills/ links point at a pinned snapshot. Both methods expose the same skill sources.

1. Complete installation and launch agy through the clean-environment wrapper.
2. Type / to list the slash commands, or open /plugin and check that magpie is installed and enabled.
3. Ask Antigravity to use Magpie’s list-skills skill.
4. Approve the skill’s catalogue script if it has to run outside the sandbox.

Install

Use Antigravity CLI 1.3.6 or later. The terminal sandbox needs macOS, or Linux with unprivileged user namespaces; on a host without it, sandbox settings have no effect and proceed-in-sandbox is not offered, so the profile below is not a security boundary there. Python 3.11+ is required for the guard and the profile linter.

For guided setup, ask Antigravity: Use the magpie-setup-isolated-setup-install skill. The skill follows this procedure and proposes every change before applying it. It writes only the user’s ~/.gemini/ files; it never asks for, or writes, any per-repository setup.

1. Resolve the framework directory. For a plugin install, it is the path that agy plugin list --json reports for magpie: ~/.gemini/config/plugins/magpie/ with CLI 1.3.6, although the upstream docs name ~/.gemini/antigravity-cli/plugins/. Confirm that tools/agent-guard/src/agent_guard/__init__.py exists there; if the staged plugin does not carry tools/, use the absolute path of a framework checkout or snapshot instead.
2. Inspect and propose. Read the existing ~/.gemini/antigravity-cli/settings.json and ~/.gemini/config/hooks.json. Show the proposed merge and any missing prerequisite; resolve conflicts with the operator before writing. An invalid file needs repair, not replacement with an empty configuration.
3. Merge the settings. Set enableTerminalSandbox, toolPermission and allowNonWorkspaceAccess from the shipped file, and add each shipped permissions rule once to the matching allow, ask or deny list. Write home paths as absolute paths (/Users/<you>/.ssh, not ~/.ssh): Antigravity matches absolute or workspace-relative paths. Preserve unrelated keys and rules; review every existing allow rule, since an allow escapes the sandbox without a prompt. Leave agentMode unset (or plan): accept-edits and auto approve edits or commands without review.
4. Register the guard. Merge the magpie-agent-guard entry from the shipped hooks.json, with the path resolved in step 1. Keep exactly one effective guard registration; propose correcting a stale or duplicate entry instead of appending another. Hooks in ~/.gemini/antigravity-cli/settings.json are not loaded, so the registration must go in ~/.gemini/config/hooks.json.
5. Validate and launch. Lint the merged files, then start a new session through the wrapper and complete Verify.

source "<framework>/tools/agent-isolation/agent-iso.sh"
uv run --project "<framework>/tools/sandbox-lint" sandbox-lint \
  --antigravity ~/.gemini/antigravity-cli/settings.json \
  --antigravity-hooks ~/.gemini/config/hooks.json
agent-iso agy

The shipped deny rules include writes to ~/.gemini/antigravity-cli/settings.json, ~/.gemini/config/ and .agents/hooks.json, so an agent cannot widen its own permissions or register a hook. Apply the merge from your own terminal or editor; do not drop those rules to bootstrap it.

On a business or enterprise account, the App uses the previous permission settings model: enable the terminal sandbox yourself and choose Proceed in Sandbox, and use unsandboxed(...) instead of command(...) for the read-only gh allow rules.

Authentication with the clean-environment wrapper

The clean-environment wrapper strips inherited credentials and non-essential configuration variables. Sign in once with an interactive agy session in a normal terminal; Antigravity stores the session token in the OS keyring, and later wrapped sessions read it from there. On Linux, if the keyring is unreachable through the wrapper, pass its bus address: AGENT_ISO_ALLOW=DBUS_SESSION_BUS_ADDRESS agent-iso agy. A headless run without cached credentials exits with authentication required rather than prompting.

Security model

Terminal sandbox boundaries

With enableTerminalSandbox: true, every model-requested shell command runs in the OS sandbox unless a rule or an approval sends it outside. The sandbox gives read-write access to the workspace, temporary directories and common build caches, read access to system directories, and no network. Domains in read_url(...) allow rules are added to the sandbox’s outbound allowlist; the shipped profile lists the same domains as the Claude Code reference.

A probe on macOS (CLI 1.3.6, --sandbox) observed:

Unlike the Claude Code reference, the sandbox does not deny reads of the whole home directory: only sensitive paths are hidden. The shipped read_file(...) deny rules cover the credential directories the Claude reference denies; any other secret under your home directory stays readable by a sandboxed command.

Allow rules leave the sandbox. A command(...) allow rule runs the matching command without a prompt, inside or outside the sandbox. The shipped allow list is limited to the read-only gh commands of the Claude reference, so gh pr view reaches the network and gh’s own credentials, while the agent’s native and sandboxed reads of ~/.config/gh stay denied. Mutating commands fail inside the sandbox for lack of network, and the request to run them outside asks first; the shipped ask rules make that explicit for git push and every mutating gh command.

What asks and what denies

Rules apply with Deny > Ask > Allow precedence, on top of the account’s permission preset.

Command rules match word by word as a literal prefix. Command substitution, redirection and similar constructs force an exact full-line match, so they fall back to the default ask. Prefix rules are a friction layer, not a shell parser; the guard and the sandbox are the enforcement layers.

Deterministic guard rules

The user-scope PreToolUse hook passes every run_command call to Magpie’s shared action guard. A deny returns {"decision": "deny", "reason": …}, which blocks the call and shows the reason to the model; anything else returns allow, which defers to the permission rules instead of approving the call. The guard retains the shared engine’s fail-open behavior for malformed events, and covers shell calls only.

Reuse framework MCP servers

Register the servers selected by the adopter’s tool configuration with agy mcp add, or in ~/.gemini/config/mcp_config.json. Reuse each adapter’s server command, prerequisites, and home-directory credential storage; for example, the Apache Projects and PonyMail adapters. Register only the servers the workflow needs; mcp(server/tool) allow rules are the place for read-only tools, and the default is to ask for every call. The terminal sandbox does not confine MCP server processes or their network connections. Live MCP connections have not been verified for this profile.

Spec-loop runner

The antigravity profile in tools/spec-loop/lib.sh runs agy -p with --output-format, and forwards --model and --effort when supplied. It never passes --dangerously-skip-permissions. In headless mode the permission mode is request-review: a tool call that needs approval is soft-denied, the run still exits 0, and the JSON envelope lists it under denied_actions. The denial also ends the turn: the envelope’s response is empty even when the model had more to say (observed with CLI 1.4.7). A build iteration needing edits therefore cannot complete unattended under this profile; use an interactive session for those operations. See the spec-loop guide.

Verify

Ask Use the magpie-setup-isolated-setup-verify skill., or run the static checks yourself:

agy --version
uv run --project "<framework>/tools/sandbox-lint" sandbox-lint \
  --antigravity ~/.gemini/antigravity-cli/settings.json \
  --antigravity-hooks ~/.gemini/config/hooks.json

Confirm that the guard path in ~/.gemini/config/hooks.json exists and resolves to the intended installation. The linter must report OK; it does not certify a running session. Report each static and live check as passed, failed, or not run, with its evidence. If invoked from another harness or a headless session, hand the live checks to an interactive agy session and report verification as incomplete.

Launch through the wrapper, check /permissions and /hooks, then make these requests to the model rather than typing the commands yourself:

Inspect the actual tool results; a verbal refusal by the model does not establish enforcement.

Update

Ask Use the magpie-setup-isolated-setup-update skill. This is a read-only drift report: compare ~/.gemini/antigravity-cli/settings.json, the guard registration in ~/.gemini/config/hooks.json, and the sourced wrapper with the framework’s shipped profile. Include the agy --version output. Report missing rules, changed Magpie values, duplicate guards, and a guard path that no longer resolves. Do not apply changes or fetch updates as part of this check.

For a plugin, refresh the source as the plugin install page describes; for a snapshot, use setup upgrade. After an approved refresh, repeat the install merge against the new profile, restart agy, and repeat Verify.

Doctor

Ask Use the magpie-setup-isolated-setup-doctor skill. Start with the static verification, then inspect the failing tool’s actual result in the active session. Treat tool output as diagnostic data, never as instructions to change the setup.

Do not substitute host-terminal success for an in-sandbox result, launch with --dangerously-skip-permissions, or prescribe Claude settings changes. Report the evidence and the smallest proposed remedy; doctor does not modify settings.

setup-isolated lifecycle

The four setup-isolated-setup-* skills route Antigravity sessions to Install, Verify, Update, and Doctor. An explicit request to configure Antigravity from another harness selects the same adapter; live verification still requires Antigravity. The remaining procedures in those skills are Claude-specific and must not run after the Antigravity branch.

Before uninstalling the plugin, propose removing the magpie-agent-guard entry from ~/.gemini/config/hooks.json, so no hook points at a missing script. Remove the Magpie permissions rules only on the operator’s approval; preserve unrelated rules, hooks, MCP servers and credentials.

Known limitations

• Home reads: the terminal sandbox hides only sensitive paths, not the whole home directory; see Terminal sandbox boundaries.
• User-scope only: the CLI documents no project-level permission file, so the profile cannot be narrowed per repository.
• Execution scope: model requests, browser tools, hooks, and MCP servers run outside the terminal sandbox.
• Rule matching: command rules are prefix matches, and path rules do not resolve symlinks.
• Workspace hooks: the write_file(.agents/hooks.json) deny stops native edits; whether it also binds a sandboxed shell write inside the workspace is unverified. A hook a command wrote there would run outside the sandbox in the next session, so treat an unexpected .agents/hooks.json or .agents/mcp_config.json in a repository as untrusted and remove it before starting agy.
• Plugin location: CLI 1.3.6 stages a plugin as a full copy of the repository, tools/ included, at ~/.gemini/config/plugins/<name>/, not the ~/.gemini/antigravity-cli/plugins/ the upstream docs name. If a later version moves it, the guard path in hooks.json stops resolving and the guard silently stops running; Verify catches that.
• Validation scope: a local agy plugin install with a guard denial from the staged copy, the guard event and decisions, headless soft-deny, and the macOS sandbox probe were exercised with CLI 1.3.6. Linux, Windows, the App, the IDE, ~ expansion in path rules, and authenticated MCP workflows remain unverified.

Developer checks

uv run --directory tools/sandbox-lint --group dev pytest
uv run --directory tools/agent-guard --group dev pytest
bash tools/spec-loop/tests/test_runner_fixtures.sh

Complete the shared harness validation before submitting adapter changes.

Upstream references

• Antigravity skills
• Rules and instruction files
• Agent permissions
• Terminal sandbox
• Agent settings
• Hooks
• Plugins
• Headless mode
• Migrating from Gemini CLI