feat(deploy): add Cloud Run sandbox support and streamline documentation

.dockerignore

@@ -0,0 +1,18 @@
+.git
+.github
+.venv
+venv/
+.pytest_cache
+.ruff_cache
+.mypy_cache
+__pycache__
+*.pyc
+*.pyo
+.coverage
+htmlcov/
+.reach/
+studies/
+dist/
+build/
+*.egg-info/
+node_modules/

.gcloudignore

@@ -0,0 +1,35 @@
+.gcloudignore
+.git
+.gitignore
+
+# Inherit rules from .gitignore (#!include: is an active gcloud directive)
+#!include:.gitignore
+
+# Ensure bundled config and skill definitions are packaged into runner build context
+!src/reach/reach.toml
+!.agents/
+!.agents/skills/
+!.agents/skills/**
+
+# CI/CD and repository metadata
+.github/
+
+# Virtual environments & local caches
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+__pycache__/
+*.pyc
+*.pyo
+.coverage
+htmlcov/
+
+# Local evaluation runs and artifacts
+.reach/
+studies/
+dist/
+build/
+*.egg-info/
+node_modules/

.github/dependabot.yml

@@ -33,3 +33,13 @@ updates:
       - github_actions
     cooldown:
       default-days: 7
+
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+    labels:
+      - dependencies
+      - npm
+    cooldown:
+      default-days: 7

.gitignore

@@ -41,6 +41,7 @@ skills-lock.json
 CONTEXT.md
 reach.toml
 reach.local.toml
+!src/reach/reach.toml
 studies/
 .reach/
 

Dockerfile

@@ -0,0 +1,57 @@
+# syntax=docker/dockerfile:1
+
+# ── Stage 1: Build virtual environment with uv ──────────────────────────────
+FROM python:3.12-slim AS builder
+
+# Copy uv binary for fast package resolution
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
+
+WORKDIR /build
+
+# Configure virtual environment in /opt/venv
+ENV VIRTUAL_ENV=/opt/venv \
+    PATH="/opt/venv/bin:$PATH"
+
+# Copy package metadata and source to install into isolated venv
+COPY pyproject.toml README.md ./
+COPY src/ src/
+
+RUN uv venv /opt/venv && \
+    uv pip install --no-cache-dir ".[antigravity-sdk]"
+
+# ── Stage 2: Minimal Runtime ────────────────────────────────────────────────
+FROM python:3.12-slim AS runtime
+
+# Install runtime dependencies (git for skill repository inspection, ca-certificates)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    ca-certificates \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy prebuilt virtual environment from builder stage
+COPY --from=builder /opt/venv /opt/venv
+
+# Configure PATH to include virtual environment and Cloud Run sandbox launcher
+ENV PATH="/opt/venv/bin:/usr/local/gcp/bin:$PATH" \
+    PYTHONUNBUFFERED=1
+
+# Create unprivileged user (UID 10001) and prepare isolated workspace.
+# Group root (GID 0) with mode 0775 allows both `--user reach` (UID 10001) and
+# rootless/user-namespace sandboxes to write `.reach/` evaluation artifacts.
+RUN groupadd -g 10001 reach && \
+    useradd -u 10001 -g reach -m -d /home/reach reach && \
+    mkdir -p /workspace && \
+    chown -R reach:root /workspace && \
+    chmod 0775 /workspace
+
+WORKDIR /workspace
+
+# Copy only resident skill catalog (avoid copying src/ or tests/ into runtime workspace)
+COPY --chown=reach:reach .agents/ /workspace/.agents/
+
+# Security note: Cloud Run's /usr/local/gcp/bin/sandbox launcher requires UID 0 in the
+# outer container to initialize /var/run/netns network namespaces before dropping privileges
+# to a non-root user inside the sandbox jail (and Cloud Run does not support runAsUser
+# overrides). For standalone local Docker runs without `sandbox do`, pass `--user reach`.
+CMD ["reach", "eval", "--agent", "antigravity-sdk", "--yes"]

biome.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.5.13/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.5.15/schema.json",
   "vcs": {
     "enabled": true,
     "clientKind": "git",

deploy/cloudrun/job.yaml

@@ -0,0 +1,62 @@
+apiVersion: run.googleapis.com/v1
+kind: Job
+metadata:
+  name: reach-eval-job
+  annotations:
+    run.googleapis.com/launch-stage: BETA
+spec:
+  template:
+    spec:
+      template:
+        spec:
+          maxRetries: 0
+          timeoutSeconds: 1800
+          containers:
+            - name: reach-eval
+              image: LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/reach-runner:latest
+              sandboxLauncher: true
+              volumeMounts:
+                - name: gemini-secret
+                  mountPath: /secrets
+                  readOnly: true
+                # Optional: mount a Cloud Storage bucket at /workspace/.reach (and pass
+                # --mount type=bind,source=/workspace/.reach,destination=/workspace/.reach)
+                # to persist evaluation artifacts beyond ephemeral sandbox exit.
+              command:
+                - /usr/local/gcp/bin/sandbox
+              args:
+                - do
+                - --allow-egress
+                - --write
+                - --env
+                - PATH=/opt/venv/bin:/usr/local/gcp/bin:/usr/local/bin:/usr/bin:/bin
+                - --env
+                - REACH_YES=1
+                - --env
+                - GEMINI_API_KEY_FILE=/secrets/GEMINI_API_KEY
+                - --mount
+                - type=bind,source=/secrets,destination=/secrets,readonly
+                - --workdir
+                - /workspace
+                - --
+                - reach
+                - eval
+                - --agent
+                - antigravity-sdk
+                - --auto
+                - --yes
+              # Scale cpu/memory (e.g. 4 vCPU / 4Gi) for large multi-worker sweeps
+              resources:
+                limits:
+                  cpu: "2"
+                  memory: 2Gi
+              env:
+                - name: REACH_YES
+                  value: "1"
+          volumes:
+            - name: gemini-secret
+              secret:
+                secretName: GEMINI_API_KEY
+                items:
+                  - key: latest
+                    path: GEMINI_API_KEY