Antigravity Sidecars for QA can run recurring background work beside the main application and start project-scoped agent conversations on a schedule. That makes them useful for unattended smoke-test triage—but only when the schedule, scope, restart behavior, evidence, duplication controls, and human handoff are tested deliberately.

This tutorial uses a synthetic application and a read-mostly triage workflow. The sidecar does not deploy, merge, file defects, or change production. It starts a bounded conversation that reviews sanitized smoke-test output and prepares an evidence-linked summary for a QA engineer.

What Google documents about Sidecars

The official Antigravity Sidecars documentation describes sidecars as background processes whose lifecycle Antigravity manages, including restart behavior after crashes or errors. Sidecars can support persistent scripts, event reactions, and scheduled recurring work.

A sidecar lives in its own directory with a sidecar.json file. It can run a command or the built-in scheduler, and it supports always, on-failure, or never restart policies. Sidecars are disabled until explicitly enabled in global configuration. A projectId can scope conversations created with the bundled agentapi command.

Runtime evidence is stored per sidecar under separate data, logs, and events directories. The scheduler accepts a standard five-field cron expression. These facts provide concrete QA contracts; they do not guarantee that an agent’s diagnosis is correct.

Choose a low-risk smoke-test use case

Create a disposable project containing a small API or web application, a deterministic smoke suite, and synthetic test results. The scheduled prompt should read an approved result file, classify failures, identify missing evidence, and recommend the next check. Keep execution, diagnosis, and action separate:

  • The test runner owns pass or fail.
  • The sidecar owns scheduling and conversation creation.
  • The agent drafts a hypothesis from bounded evidence.
  • A QA engineer owns reruns, defects, fixes, and release decisions.

Step 1: define the scheduling contract

Before creating configuration, write down the expected timezone, cron expression, maximum acceptable launch delay, overlap behavior, missed-run behavior, and maintenance window. Antigravity’s scheduler uses five cron fields, so seconds-level scheduling is outside this contract.

For the first test, schedule a harmless run every few minutes in a disposable environment. Record the expected timestamps and compare them with the actual event files. After validation, change to the real cadence. Do not test by pointing a new sidecar at production evidence.

Step 2: create a minimal sidecar

Use one sidecar directory with a small configuration. The built-in schedule should call agentapi new-conversation with a fixed prompt. Assign the intended project identifier in user configuration; Google documents that creating conversations requires projectId.

{
  "description": "Scheduled QA smoke-triage exercise",
  "builtin": "schedule",
  "args": [
    "15 6 * * 1-5",
    "agentapi",
    "new-conversation",
    "Review the approved synthetic smoke-test result. Cite evidence, label uncertainty, make no changes, and stop for human review."
  ]
}

Keep secrets out of args and screenshots. If helper scripts need state, write only to the documented sidecar data directory and apply retention controls.

Step 3: scope the project and permissions

The Projects documentation says projects define folders, settings, and permissions for their agents. The permissions guide describes deny, ask, and allow lists with precedence Deny > Ask > Allow.

Create a dedicated QA project containing only the synthetic repository and sanitized result directory. Deny access to secrets, deployment scripts, production URLs, credential folders, destructive commands, and mutation-capable MCP tools. Allow only the exact reads and test commands needed. Remember that unattended work cannot safely depend on an interactive approval appearing at 3 a.m.

Step 4: validate enable and disable behavior

Because sidecars are disabled until explicitly enabled, test both states. With the sidecar disabled, wait through at least two expected schedule windows and verify no conversation, log, event, or side effect appears. Enable it, then verify exactly one launch in the next window.

Disable it again during a controlled period and confirm future launches stop. A disabled sidecar should be part of the rollback plan, not just an installation detail.

Step 5: verify logs, events, and persistent data

For each scheduled attempt, reconcile three evidence sources:

Evidence QA assertion Failure signal
Timestamped logs Startup, standard output, and error output are captured Missing or unbounded logs
Agent API events One conversation creation is recorded for the run Zero, duplicate, or malformed events
Persistent data Run key and last-success marker update atomically Corruption or secret leakage

Use a run key derived from the schedule window and project, not from model prose. Store it before starting downstream work. If the same key is seen again, quarantine the duplicate rather than producing another triage conversation.

Step 6: test restart policies

Exercise never, on-failure, and always in a temporary sidecar. Simulate a clean exit, a controlled nonzero exit, and a crash. Count restarts and measure the delay. Verify that the sidecar does not create repeated conversations after a failure.

A restart loop is especially dangerous when each startup triggers external work. Add an attempt counter, cooldown, and circuit breaker in the helper process. The documented restart policy controls process lifecycle; your QA design must control business-level duplication.

Step 7: test overlap and slow runs

Make one synthetic triage run last longer than the schedule interval. Verify whether a second invocation starts, queues, skips, or collides. The sidecar documentation does not promise a QA-specific overlap policy, so implement and test your own lock with an expiry and ownership token.

Test stale-lock recovery, two simultaneous starters, process termination while holding the lock, and a clock change. The expected result is one active run per window and a visible skipped or recovered status for every other attempt.

Step 8: inject failures systematically

  1. Missing projectId: conversation creation should fail visibly.
  2. Unknown project: no conversation should appear elsewhere.
  3. Malformed cron: configuration should be rejected or remain inactive.
  4. Missing result file: agent should report insufficient evidence.
  5. Prompt injection inside the test log: treat it as data, not instruction.
  6. Permission denial: protected resources remain unchanged.
  7. Agent API error: bounded retry, then an explicit failed state.
  8. Full data volume or unwritable log path: no silent success.
  9. Application restart: no duplicate work for the same window.
  10. Disabled sidecar: no launch across repeated windows.

Step 9: validate the triage output

Use a fixed template requiring run ID, deterministic test result, cited log lines, observed symptoms, hypotheses, missing evidence, next checks, and human_review_required. Reject invented filenames, unsupported root causes, secret-like strings, and recommendations that exceed the project’s permissions.

Rerun the same fixture several times and compare evidence grounding and required fields, not exact wording. The agent’s response is probabilistic even when scheduling is deterministic.

Screenshot plan

Capture the synthetic project, sidecar directory, redacted scheduler configuration, disabled-state proof, enabled launch, logs and event files, project permissions, controlled crash and restart evidence, overlap lock result, and final human triage review. Hide usernames, machine paths, project IDs, endpoints, and credentials.

Release checklist

  • The cron schedule and timezone expectation are documented.
  • The sidecar is explicitly enabled only after validation.
  • The correct project ID is used.
  • Permissions are least privilege and production access is denied.
  • Each window has an idempotent run key.
  • Overlap, crash, restart, and stale-lock cases pass.
  • Logs, events, and persistent data reconcile.
  • Retries, retention, and storage limits are bounded.
  • The agent output cites approved evidence and labels uncertainty.
  • A human QA engineer approves any follow-up action.

Limits to keep visible

Sidecars improve scheduling and lifecycle management, not test correctness. A process can run on time and still use stale evidence, create duplicate conversations, or produce a wrong diagnosis. Project permissions and default guardrails reduce risk but still need negative tests.

The strongest pattern is: deterministic smoke tests produce sanitized evidence, a project-scoped sidecar starts one bounded conversation, logs and events prove what happened, and a human decides what to do next.

Official sources