antigravity-runner¶

Status: Preview | Last reviewed: 2026-06-09

Sandboxed Google Antigravity runtime for Assistant Agent chat stages that opt into local workspace tools.

Source¶

apps/antigravity-runner

Runtime¶

Aspect	Value
Language	Python 3.13
Framework	FastAPI
Port	8011
Sandbox	Dedicated pod/process, non-root user, tmpfs ephemeral workspace, NetworkPolicy/proxy egress, optional gVisor

What it does¶

Receives an internal streaming turn request from ai-orchestrator.
Creates a fresh per-chat workspace under ANTIGRAVITY_RUNNER_WORKSPACE_DIR.
Starts a Google Antigravity Agent with local tools scoped to that workspace when sandbox.enabled=true.
Seeds Antigravity workspace context through root AGENTS.md and GEMINI.md, a machine-readable .trueserve/ catalog, and a generated .agents/plugins/trueserve/ plugin containing runtime rules and skills.
Streams Antigravity text, reasoning, tool calls, tool results, command approval requests, and artifact summaries back as NDJSON.
When Antigravity calls a TrueServe-hosted tool, emits a host_tool_call event and waits for ai-orchestrator to POST the result back.
Redacts the ephemeral workspace path/name from streamed text, reasoning, tool arguments/results, errors, and artifact summaries before anything renders to a surface.
Deletes the ephemeral workspace when the turn/session stream closes.

The runner keeps the TrueServe conversation_id for correlation only. In the Antigravity SDK, conversation_id means "resume this saved cascade"; because v1 workspaces are ephemeral per turn, the runner does not pass the TrueServe id into LocalAgentConfig unless a matching saved trajectory is available.

Tool lanes¶

Lane	Owner	Notes
TrueServe tools	ai-orchestrator + agent-host	Existing MCP/API/Python/workflow/A2UI tools execute through normal registered callbacks and policy.
Antigravity local tools	antigravity-runner	File list/search/view/create/edit and command execution run only inside the ephemeral workspace.
Antigravity skills	ai-manager + ai-orchestrator + antigravity-runner	Library skills and inline skills compile into `.agents/plugins/trueserve/skills/<skill>/SKILL.md` packages and are passed as Antigravity `skills_paths`.

Every turn also gets generated workspace guidance:

AGENTS.md explains that the agent is in a temporary TrueServe workspace, should refer to it as "the workspace", must stay inside it, and should recover cleanly from tool failures or denied commands.
GEMINI.md points Antigravity-compatible context loaders back to AGENTS.md.
.trueserve/environment.json records sandbox state, local tool availability, approval posture, egress posture, skill names, and the host tool catalog location.
.trueserve/tools.json lists configured TrueServe host callable tools and JSON schemas.
.agents/plugins/trueserve/plugin.json identifies the generated TrueServe plugin bundle.
.agents/plugins/trueserve/rules/trueserve-runtime.md records runtime rules for path redaction, host-bridge MCP execution, and artifact placement.
.agents/plugins/trueserve/skills/trueserve-environment, .agents/plugins/trueserve/skills/trueserve-tools, and one tool-<name> directory per configured host tool are passed to the SDK as skills_paths.
Selected library and inline skills become additional skills/<skill-slug>/SKILL.md packages with tools.json, examples.json, and optional text/markdown/JSON resources.

The runner passes the ephemeral workspace path to LocalAgentConfig.workspaces on every turn so Antigravity has an active, bootstrapped workspace and does not fall back to its generic "no active workspace" onboarding. Local file/search/write/command capabilities are still controlled only by sandbox.enabled; when that flag is false, built-in local tools remain disabled.

If a turn has no local workspace tools, no user-supplied skills, and no governed business tools beyond lifecycle helpers such as end_session, the runner still seeds AGENTS.md/GEMINI.md and passes the active workspace, but it does not pass generated skill paths. It sends direct runtime instructions telling Antigravity not to introduce itself as a generic Antigravity product assistant, not to inspect files or discover tools, and to answer with a useful general framework while asking the user to connect or provide the required data for specific trend analysis.

Preview policy is intentionally narrow:

sandbox.workspace_mode must be ephemeral_session.
sandbox.enabled controls whether Antigravity local file/search/write/command tools are exposed. It defaults to false on the service definition and must be opted into per Assistant Agent node.
sandbox.command_policy must be ask_user; without an interactive approval path, commands are denied.
sandbox.egress_policy must be proxy_allowlist.
Antigravity subagents are disabled; TrueServe subagents still work through the governed tool bridge.
Workspace skill seed files and Antigravity internal state directories are excluded from artifact summaries; only workspace outputs are shown.
Generated AGENTS.md, GEMINI.md, .agents/, .trueserve/, .skills/, and Antigravity state directories are excluded from artifact summaries.
The preview defaults Antigravity thinking_level to minimal. If an older node still has medium or high saved, ai-orchestrator clamps it to minimal for blank-context turns so reasoning traces do not fill with repeated tool-discovery attempts.

Recovery and errors¶

ai-orchestrator retries a failed runner turn once by default, but only if no text, reasoning, or tool trace has streamed yet. This avoids duplicated visible output. If the retry also fails, or if the failure happens after visible output has started, the orchestrator emits an antigravity_error tool event with status=error instead of writing an "Antigravity error..." message into the assistant transcript.

Configure recovery_attempts on the LLM node to 0, 1, or 2. Wall-time limit failures from the runner are treated the same way: retry when safe, otherwise surface as the error event.

Skills¶

Antigravity Assistant Agent stages use Skills as the main capability abstraction:

Library Skills live in the tenant-scoped agent_skills table and can be reused across Antigravity nodes.
Inline Skills live in the node config as inline_skills and are compiled only for that node until the user saves them to the library.
Direct legacy tools selections still run and are mirrored into a generated "Legacy TrueServe Tools" skill at runtime.
Native Antigravity MCP config is not generated in v1. MCP-backed tools selected inside either skill type execute through the existing TrueServe host bridge.

The runtime node contract is:

{
  "skill_ids": ["<agent_skills.id>"],
  "inline_skills": [
    {
      "id": "inline-...",
      "name": "Executive KPI Summary",
      "description": "Summarize KPIs for leadership.",
      "instructions": "Use governed metric tools before writing the summary.",
      "tool_refs": [{ "tool_id": "<tool_configs.id>", "type_id": "mcp" }],
      "resources": [{ "path": "guidance.md", "content": "# Notes\n" }]
    }
  ],
  "tools": ["builtin:end_session"]
}

ai-orchestrator resolves skill_ids, merges inline_skills, adds the referenced tool ids to the normal governed tool resolution path, and sends compiled skill packages to the runner. The runner writes those packages under .agents/plugins/trueserve/skills/ and passes each directory through skills_paths.

The advanced raw skills config remains supported for compatibility. It accepts either a JSON array or an object with a skills array. Each skill can include:

{
  "skills": [
    {
      "name": "Research Pack",
      "description": "Curated context for this chat.",
      "instructions": "Use the provided notes when answering.",
      "files": [
        { "path": "notes/summary.md", "content": "# Summary\n..." }
      ],
      "data": { "source": "internal-export" }
    }
  ]
}

The runner writes these files inside the ephemeral workspace, rejects absolute paths and .. traversal, and passes the skill directories to the SDK. Skills can seed small text, markdown, or JSON context files or collected data; they do not grant command execution or extra filesystem access by themselves.

Configured TrueServe tools are automatically mirrored into generated skills. Prefer the Skill Builder for new skills; use the advanced raw skills config only for compatibility or low-level experiments.

Vanguard¶

Started by start-antigravity-runner.sh under Overmind.

overmind restart antigravity-runner
overmind connect antigravity-runner

Local dev defaults to real SDK mode. The launcher builds and runs apps/antigravity-runner/Dockerfile when ANTIGRAVITY_RUNNER_FAKE=false because the Google Antigravity preview wheel starts a bundled harness that requires a newer glibc than the host devcontainer image provides. Set ANTIGRAVITY_RUNNER_FAKE=true only for deterministic local tests of the stream/tool bridge.

Useful local toggles:

ANTIGRAVITY_RUNNER_USE_DOCKER=true runs real SDK mode in the local Docker image.
ANTIGRAVITY_RUNNER_USE_DOCKER=false tries host venv mode; this is expected to fail in older devcontainers with a glibc harness error.
ANTIGRAVITY_RUNNER_FAKE=true disables SDK calls and emits deterministic test events only.

Production¶

Helm chart at charts/antigravity-runner. Enable gVisor where available, keep readOnlyRootFilesystem=true, and keep egress default-deny except for the approved proxy.