# Antigravity Execution Fabric

An MCP bridge that lets one Antigravity IDE explicitly control multiple isolated Antigravity CLI workers. The IDE chooses the worker, model, skills, task, review, retry, and artifact. The bridge executes those decisions and preserves evidence.

```mermaid
flowchart TD
    IDE[Main Antigravity IDE] -->|Explicit MCP calls| MCP[Deterministic command server]
    MCP --> DB[(SQLite WAL metadata)]
    MCP --> A[Isolated CLI worker A]
    MCP --> B[Isolated CLI worker B]
    MCP --> C[Isolated CLI worker C]
    A --> Files[Private immutable artifact exports]
    B --> Files
    C --> Files
    Files -->|Chunks and SHA-256| IDE
```

## Installation

Linux, Python 3.11+, authenticated Antigravity CLI, bubblewrap, util-linux, iproute2, and root access for the trusted launcher are required. Install into a private directory. Never grant untrusted users write access to the launcher or deployment configuration.

```bash
python3 -m venv .venv
.venv/bin/pip install -e '.[test]'
```

Copy the settings described in `.env.example` into private environment configuration. The supplied startup scripts alternatively read `private/deployment.json` with the same environment keys. That file contains account mappings and installation paths; it must have mode 0600 and stay out of Git.

`FABRIC_ACCOUNTS` maps explicit profile IDs to already authenticated local CLI account names. Each registered worker requires a distinct profile. A profile lock also coordinates admission with other deployments using `/run/agy-account-locks`. The server never chooses a replacement account.

The gateway permits only explicitly configured public provider TLS hosts. Set `FABRIC_PROVIDER_HOSTS` from your verified CLI requirements, then start it:

```bash
.venv/bin/python scripts/start_gateway.py
```

In another process, start the STDIO command server:

```bash
.venv/bin/python scripts/serve_stdio.py
```

STDIO is the supported transport. For a remote VPS, use authenticated SSH as the transport; see [Antigravity setup](docs/ANTIGRAVITY_SETUP.md). No MCP HTTP listener is enabled.

## Explicit IDE workflow

1. `discover_antigravity_capabilities()` returns the installed version, help evidence, and model catalog.
2. `create_worker(worker_id="frontend", profile="profile-1")` registers the chosen account.
3. `start_worker(worker_id="frontend")` makes it available. CLI processes are launched per task.
4. `set_worker_model(worker_id="frontend", model="ACTUAL_CATALOG_MODEL")` configures the chosen model. Configuration alone does not prove its effective selection.
5. `register_skill(specification={...})` creates an immutable versioned skill. Use its returned ID in `assign_worker_skills`.
6. `execute_task(worker_id="frontend", task="Create index.html", expected_outputs=["index.html"])` reserves that exact worker and returns a task ID.
7. Poll `get_task_status`, inspect `get_task_result`, and read bounded `get_worker_logs`.
8. Call `list_worker_artifacts`, then `fetch_artifact` or `fetch_task_artifact`. Decode base64 chunks and verify chunk and whole-file SHA-256.
9. `cancel_task` terminates only the recorded process identity and its execution group. `stop_worker` also cancels its active task.
10. Review the evidence in the IDE. Only the IDE can decide to retry or submit additional work.

Each new task receives a generated workspace. User-supplied filesystem paths are rejected. Skills are provided as explicit prompt context and task-local `.agents/skills` files; there is no invented CLI `--skill` flag.

## Verification

```bash
.venv/bin/ruff check server tests scripts
.venv/bin/python -m pytest -q
```

The test suite covers ten simultaneous simulated workers, file integrity, MCP calls, cancellation, timeout, invalid models, immutable skill versions, path attacks, and restart persistence. Simulated tests do not prove provider execution. The opt-in real test submits harmless file-creation requests and stores private evidence:

```bash
.venv/bin/python scripts/real_e2e.py ACTUAL_CATALOG_MODEL 2
```

Inspect [the verification report](FINAL_VERIFICATION_REPORT.md) for measured results and limitations. No feature is proven merely by its presence in source code.

![Durations from one real ten-worker concurrent verification run](docs/images/worker-durations.svg)

The recorded run verified exact content, worker mapping and SHA-256 for all ten workers. These times include startup and provider execution; they are not a general performance benchmark.

## Documentation

- [Architecture](docs/ARCHITECTURE.md)
- [MCP tools](docs/MCP_TOOLS.md)
- [Antigravity setup](docs/ANTIGRAVITY_SETUP.md)
- [Troubleshooting](docs/TROUBLESHOOTING.md)
- [Security](SECURITY.md)

Keywords: Antigravity, MCP, Model Context Protocol, CLI workers, explicit model selection, artifact transfer, asyncio, SQLite, SHA-256, Linux isolation.