Deep Dive into Sandbox Tech: From Local Isolation to Cloud Hosting with Google Antigravity

In the era of modern software development and AI Agent collaborative programming, "Sandbox" technology has become the core cornerstone for protecting developers' host systems, isolating untrusted third-party scripts, and supporting the autonomous execution of Agents.

This article, combined with practical cases from Google Antigravity, will deeply analyze the underlying execution mechanisms, configuration systems, and Telegram Bot integration code of the Unsandboxed (Raw Host), Local Sandbox, and Cloud Sandbox modes, deconstructing their core differences through graphical workflows.

1. In-Depth Analysis and Comparison of Three Execution Modes

🔓 1.1 Unsandboxed / Raw Host Mode

• Definition: The Agent runs directly within the host machine's file system and shell under the identity of the currently logged-in user on your physical machine.
• Security: Extremely Low. There is no isolation mechanism. If the Agent executes a malicious script or an accidental deletion command (e.g., rm -rf /), the host system will be immediately corrupted.
• File Access: Can directly read and write any user files on the host machine (including the local ~/.ssh key directory, password databases, etc.).
• Resource Consumption: Fully consumes the CPU, memory, and battery of the local physical machine.

🛡️ 1.2 Local Sandbox Mode

• Definition: Utilizes OS kernel-level lightweight virtual isolation technology to "lock down" and control the execution environment.
• Security: High. The Agent is locked within a virtual container and cannot snoop on or tamper with any real system files outside the sandbox.
• Underlying Mechanism:
  • macOS: Uses the system kernel's sandbox-exec for process restriction.
  • Linux: Uses Google's open-source nsjail (cgroups / namespaces) technology for isolation.
  • Windows: Uses the AppContainer mechanism.
• Resource Consumption: Consumes the computing resources (CPU/memory) of the local physical machine.

☁️ 1.3 Cloud Sandbox Mode

• Definition: The sandbox is fully managed in Google Cloud data centers, physically completely isolated from the developer's local physical machine.
• Security: Extreme (Absolutely Safe).
• Underlying Mechanism: Upon initiating an API call, Google Cloud dynamically provisions (configures and starts) an Ephemeral Linux Container in the cloud within seconds, and completely physically destroys it after execution completes or the TTL expires.
• Network and Storage: Runs by default in Google's Virtual Private Cloud (VPC), with the egress IP belonging to Google Cloud. State and file persistence across multiple tasks can be achieved via API.
• Resource Consumption: Consumes zero CPU/memory/battery of the local computer; it utilizes cloud-based Serverless computing power.

2. Experimental Project: Cloud Sandbox Scheduled Telegram Broadcaster Requirements Specification

🎯 2.1 Core Project Requirements and Ultimate Goal

The core business requirement of this project is: To create a secure, isolated sandbox environment and run an automated telemetry program within it as a resident Daemon. The program must automatically capture the sandbox's current outbound public egress IP, its physical geographic location (country, province, city), and real-time meteorological metrics (weather conditions and temperature) every 10 minutes, and securely push this data to the developer's personal Telegram Bot for real-time automated broadcasting via a strongly encrypted HTTPS protocol.

To ensure this goal is achieved with 100% stability in a dynamic and restricted cloud sandbox environment, the program is endowed with the following refined functions and design definitions:

🎯 2.2 Core Business Function Breakdown

1. Self-Probing:
   • The program must automatically identify which physical Google Cloud data center (city, region, and country) the current sandbox is provisioned in.
   • Automatically extract the public egress IP and Internet Service Provider (ISP) information of the current sandbox session for network auditing.
2. Telemetry Data Collection:
   • Seamlessly invoke external weather APIs to automatically fetch real-time meteorological metrics (weather conditions, temperature, etc.) based on the sandbox's current physical IP location.
3. Telegram Telemetry Push:
   • Construct a unified data dashboard and automatically push it in a formatted manner to the designated Telegram Bot chat room.
4. Scheduling Modes:
   • Single Audit Mode (--once): Execute self-probing, collection, and pushing once, then exit immediately, facilitating rapid cold starts or integration into broader automated pipelines.
   • Background Daemon Mode (--daemon <seconds>): Keep the program resident in the sandbox background, automatically looping the above tasks at specified second intervals (e.g., every 600 seconds / 10 minutes).

🛡️ 2.2 Extreme Sandbox Compatibility and Non-Functional Requirements

• Zero External Library Dependencies (Zero-Dependency):
  • Cloud sandboxes are often brand-new, highly secure, minimal Linux containers. Pulling third-party libraries (like requests) not only increases network cold-start latency but is also highly likely to be blocked by sandbox network whitelists.
  • Requirement: The code must be written 100% using Python's built-in standard libraries (only using urllib, json, ssl, etc.) to ensure it works "out-of-the-box" in any ephemeral sandbox spun up in seconds.
• Physical Isolation of Key Configurations (Decoupled Credentials):
  • Code in the sandbox often needs to be committed to version control systems; confidential information like Bot Tokens must absolutely not be hardcoded.
  • Requirement: Use a standard .env configuration file to host API Keys. Read them via environment variables after development, completely delineating the boundary between code logic and key credentials.

3. System Software and Environmental Topology Architecture Design (System Architecture & Topology)

To achieve the aforementioned design goals of strong isolation, high availability, and zero dependencies, we have designed the following layered integration topology architecture for this Agent application:

+-----------------------------------------------------------------------------------+
|                       Host and Sandbox Physical Execution Boundary                |
|                                                                                   |
|  +-----------------------------------------------------------------------------+  |
|  |             Google Cloud / Local Linux Sandbox (Execution Environment)      |  |
|  |                                                                             |  |
|  |    +-------------------------------------------------------------------+    |  |
|  |    | 1. Configuration Layer                                            |    |  |
|  |    |    - Map .env file (TELEGRAM_BOT_TOKEN / CHAT_ID)                 |    |  |
|  |    +------------------+------------------------------------------------+    |  |
|  |                       | (Read & Inject)                                     |  |
|  |                       v                                                     |  |
|  |    +-------------------------------------------------------------------+    |  |
|  |    | 2. Execution Core                                                 |    |  |
|  |    |    - Python Daemon Loop Scheduling Engine (while True)            |    |  |
|  |    |    - Exception and TLS Handshake Failure Capture Filter           |    |  |
|  |    +------------------+------------------------------------------------+    |  |
|  |                       | (Trigger Self-Probe)                                |  |
|  |                       v                                                     |  |
|  |    +-------------------------------------------------------------------+    |  |
|  |    | 3. Telemetry Engine                                               |    |  |
|  |    |    - Pure urllib Interface                                        |    |  |
|  |    |    - ipinfo.io API (Fetch Egress IP and Location e.g., Toronto)   |    |  |
|  |    |    - wttr.in Weather API (Fetch Temperature and Weather)          |    |  |
|  |    +------------------+------------------------------------------------+    |  |
|  |                       | (Send TLS Handshake Payload)                        |  |
|  |                       v                                                     |  |
|  |    +-------------------------------------------------------------------+    |  |
|  |    | 4. Egress Network Layer                                           |    |  |
|  |    |    - Sandbox Mesh VPC Virtual NIC (Toronto Egress)                |    |  |
|  |    +------------------+------------------------------------------------+    |  |
|  +-----------------------|-----------------------------------------------------+  |
+--------------------------|--------------------------------------------------------+
                           |
                           | (SSL / TLS 1.3 Secure Link Traversal)
                           v
        +------------------+------------------+
        | Telegram Cloud Servers (Telegram Bot API) |
        +------------------+------------------+
                           |
                           | (Push Message)
                           v
        +------------------+------------------+
        | User Physical Terminal (Telegram Mobile App) |
        +-------------------------------------+

📦 Detailed Explanation of the Four-Layer Architecture:

1. Configuration Layer: Responsible for implementing the "decoupled storage" of the application. Upon program startup, a custom load_env() parsing module securely injects the encrypted configuration file from the disk into runtime memory, preventing Token exposure in the event of code leakage.
2. Execution Core Layer: The core state machine at runtime. It is responsible for controlling the timer loop and capturing all underlying Alert exceptions during network jitter and SSL/TLS handshakes, ensuring the process does not crash and exit due to an accidental network packet loss or TLS downgrade rejection.
3. Telemetry Engine Layer: The technical highlight of the program. It bypasses third-party libraries, directly constructs Raw HTTP Headers in memory, masquerades as curl or a Mozilla browser, fetches geographic and meteorological information respectively, and cleans and reconstructs the returned semi-structured data into Markdown data entities.
4. Egress Network and Communication Layer: Relies on the sandbox's virtual network stack. Combined with Google Cloud / local network drivers, it strongly encrypts data packets via the TLS protocol, ultimately pushing the state to global Telegram servers.

4. Core Configuration Comparison of the Three Modes

In the Antigravity client, the configuration file is located at ~/.gemini/antigravity-cli/settings.json. You can switch between different modes through combinations of the following fields:

4.1 Mode Configuration Comparison Table

4.2 Configuration File Examples

📄 Local Sandbox Configuration (`settings.json`)

{
  "enableTerminalSandbox": true,
  "terminalExecutionPolicy": "proceed-in-sandbox"
}

📄 Cloud Sandbox Configuration (`settings.json`)

{
  "enableTerminalSandbox": true,
  "cloudSandbox": {
    "provider": "google-cloud",
    "ttlMinutes": 35,
    "autoDestroyOnIdle": true
  }
}

5. Minimalist, High-Compatibility Sandbox Execution Code Implementationl Linux Container (ephemeral isolated container), and is **completely physically destroyed** after execution completes or the TTL expires.

• Network and Storage: Runs by default in Google's Virtual Private Cloud (VPC), with the egress IP belonging to Google Cloud. State and file persistence across multiple tasks can be achieved via API.
• Resource Consumption: Consumes zero CPU/memory/battery of the local computer; it utilizes cloud-based Serverless computing power.

2. Core Configuration Comparison of the Three Modes

In the Antigravity client, the configuration file is located at ~/.gemini/antigravity-cli/settings.json. You can switch between different modes through combinations of the following fields:

2.1 Mode Configuration Comparison Table

2.2 Configuration File Examples

📄 Local Sandbox Configuration (`settings.json`)

{
  "enableTerminalSandbox": true,
  "terminalExecutionPolicy": "proceed-in-sandbox"
}

📄 Cloud Sandbox Configuration (`settings.json`)

{
  "enableTerminalSandbox": true,
  "cloudSandbox": {
    "provider": "google-cloud",
    "ttlMinutes": 30,
    "autoDestroyOnIdle": true
  }
}

3. Minimalist, High-Compatibility Sandbox Execution Code Implementation

To meet the cloud sandbox requirements of "fast cold start and no redundant dependencies", we have written a high-dimensional environment probing and Telegram notification script that relies solely on the Python 3 standard library (without using any pip third-party packages): telegram_cron_simulator.py.

📄 Security Credential Configuration File (`.env`)

TELEGRAM_BOT_TOKEN=8763417888:AAE3U-xxxxxx
TELEGRAM_CHAT_ID=8250511888

📄 Sandbox Main Program Code (`telegram_cron_simulator.py`)

#!/usr/bin/env python3
import os
import sys
import time
import urllib.request
import urllib.parse
import json
from datetime import datetime

def load_env():
    env_file = ".env"
    if not os.path.exists(env_file):
        env_file = os.path.join(os.path.dirname(__file__), ".env")
        if not os.path.exists(env_file):
            return {}
    config = {}
    with open(env_file, "r") as f:
        for line in f:
            line = line.strip()
            if not line or line.startswith("#"):
                continue
            if "=" in line:
                key, val = line.split("=", 1)
                config[key.strip()] = val.strip()
    return config

def get_sandbox_network_info():
    """Probe the sandbox's public IP and geographic location via ipinfo.io"""
    try:
        req = urllib.request.Request("https://ipinfo.io/json", headers={'User-Agent': 'Mozilla/5.0'})
        with urllib.request.urlopen(req, timeout=5) as response:
            data = json.loads(response.read().decode())
            return {
                "ip": data.get("ip", "Unknown IP"),
                "city": data.get("city", "Unknown City"),
                "region": data.get("region", "Unknown Region"),
                "country": data.get("country", "Unknown Country"),
                "org": data.get("org", "Unknown ISP")
            }
    except Exception as e:
        return {"ip": "Unknown IP", "city": "Unknown City", "region": "Unknown Region", "country": "Unknown Country", "org": str(e)}

def get_weather(city):
    """Probe local real-time weather using wttr.in without an API key"""
    if not city or city == "Unknown City":
        url = "https://wttr.in?format=%C+%t"
    else:
        city_encoded = urllib.parse.quote(city)
        url = f"https://wttr.in/{city_encoded}?format=%C+%t"
    try:
        req = urllib.request.Request(url, headers={'User-Agent': 'curl/7.79.1'})
        with urllib.request.urlopen(req, timeout=5) as response:
            return response.read().decode('utf-8').strip()
    except Exception as e:
        return f"Weather unavailable ({str(e)})"

def send_telegram_message(token, chat_id, message):
    url = f"https://api.telegram.org/bot{token}/sendMessage"
    payload = urllib.parse.urlencode({"chat_id": chat_id, "text": message, "parse_mode": "Markdown"}).encode("utf-8")
    req = urllib.request.Request(url, data=payload, headers={"User-Agent": "Mozilla/5.0"})
    try:
        with urllib.request.urlopen(req, timeout=10) as response:
            res_data = json.loads(response.read().decode())
            return res_data.get("ok"), "Success"
    except Exception as e:
        return False, str(e)

4. Architecture Configuration and Execution Flowchart (Mermaid)

The flowchart below vividly illustrates how Antigravity, under different configurations, schedules and determines which sandbox environment the Agent commands are executed in, as well as the final communication link of the Telegram Bot:

flowchart TD
    Start(["Developer enters command agy"]) --> ReadConfig["Read settings.json configuration file"]
    
    ReadConfig --> CheckSandboxEnabled{"enableTerminalSandbox == true?"}
    
    %% Unsandboxed Route
    CheckSandboxEnabled -- No --> UnsandboxedRun["Unsandboxed Native Mode (Raw Local)"]
    UnsandboxedRun --> HostShell["Direct connection to local terminal shell (UID 501 / root)"]
    HostShell --> LocalWrite["Directly modify local physical hard drive"]
    
    %% Sandboxed Route
    CheckSandboxEnabled -- Yes --> CheckCloudProvider{"Does cloudSandbox block exist?"}
    
    %% Local Sandbox Route
    CheckCloudProvider -- No --> LocalSandboxRun["Local Sandbox Mode (Local Sandbox)"]
    LocalSandboxRun --> MacSandbox["macOS sandbox-exec isolation mesh"]
    MacSandbox --> LocalJail["Local hard drive isolation (CWD restriction)"]
    
    %% Cloud/Docker Sandbox Route
    CheckCloudProvider -- Yes --> CheckProvider{"What is the value of provider?"}
    CheckProvider -- "google-cloud" --> CloudSandboxRun["Cloud Managed Sandbox Mode"]
    CloudSandboxRun --> GCPContainer["Google Cloud Ephemeral Container"]
    GCPContainer --> GcpNetwork["GCP VPC network egress (Toronto AS20473)"]
    
    CheckProvider -- "docker" --> LocalDockerRun["Local Docker Sandbox Mode"]
    LocalDockerRun --> LocalDockerContainer["Spin up lightweight local Docker container"]
    LocalDockerContainer --> LocalDockerNetwork["Share local network"]
    
    %% Telegram Event Flow
    GcpNetwork & LocalJail & LocalDockerNetwork --> ExecApp["Execute telegram_cron_simulator.py"]
    ExecApp --> ReadEnv["Read .env key configuration file"]
    ReadEnv --> IpInfoProbe["Call ipinfo.io to fetch sandbox egress IP / geographic location"]
    IpInfoProbe --> WttrProbe["Call wttr.in to fetch local real-time weather"]
    WttrProbe --> TelegramApi["Call Telegram API (api.telegram.org)"]
    TelegramApi --> UserTelegram["User's mobile Telegram App receives beautiful Tick message"]

    style UnsandboxedRun fill:#ff9999,stroke:#ff3333,stroke-width:2px;
    style LocalSandboxRun fill:#ffff99,stroke:#cccc00,stroke-width:2px;
    style CloudSandboxRun fill:#99ff99,stroke:#33cc33,stroke-width:2px;
    style UserTelegram fill:#99ccff,stroke:#3333ff,stroke-width:2px;

5. Practical Execution Case Study and TLS Handshake Troubleshooting (Case Study & SSL/TLS Debugging)

In our practical execution, you received the following extremely valuable real execution log on your mobile Telegram:

Sandbox Clock Tick #5

📍 Location: Toronto, Ontario
🌐 Egress IP: 155.138.147.192
🌤️ Weather: Weather unavailable (<urlopen error [SSL: TLSV1_ALERT_PROTOCOL_VERSION] tlsv1 alert protocol version (_ssl.c:1129)>)
🕒 Current Time: 2026-05-23 13:11:41

🐳 Environment: Sandbox Daemon Active

🔍 Multi-Dimensional Deep Analysis of Execution Results

1) 📍 Consistency of Location and Egress IP

• Egress IP: 155.138.147.192.
• Geographic Location: Toronto, Ontario (Toronto, Ontario, Canada).
• Analysis: This perfectly matches our network probing results. It indicates that all outbound traffic from the Python process running in the sandbox is routed through the Toronto gateway.

2) ❌ Classic Failure Analysis: `TLSV1_ALERT_PROTOCOL_VERSION` Error

This is the most technically significant core highlight of this experiment.

• Symptom: An SSL: TLSV1_ALERT_PROTOCOL_VERSION exception was thrown when fetching the weather.
• Root Cause Analysis:
  • The weather data source wttr.in is hosted behind a modern cloud CDN (like Cloudflare). For security reasons, the CDN strictly requires clients to use TLS 1.2 or TLS 1.3 protocols for encrypted handshakes and rejects all older versions of TLS handshakes.
  • When our Python script initiated the urlopen request in your local Mac's legacy Python/OpenSSL runtime environment, the local OpenSSL library, due to an older version or incorrect default negotiation strategy, attempted to "knock on the door" using the deprecated TLS 1.0 or TLS 1.1 protocols.
  • Consequently, Cloudflare triggered a security alert and directly sent a TLSv1 Alert Protocol Version handshake rejection signal to your Python process, causing the network request to abort.

🐳 The Golden Value of the Managed Cloud Sandbox

This TLS error proves with facts exactly why we need a cloud-managed sandbox!

1. Completely Standardized Environment:
   • Drawbacks of Local Environments: The versions of OpenSSL, Python, and system certificate libraries installed on every developer's Mac/Windows computer vary wildly. This easily leads to the classic "it works on my machine, but fails on yours" environment inconsistency problem (such as this TLS negotiation failure).
   • Advantages of Cloud Sandboxes: The Ephemeral Linux container automatically allocated by Google Cloud is a highly standardized, pristine environment pre-installed with the latest security patches and OpenSSL 1.1.1+/3.0+ libraries. When handshaking in the cloud, it defaults to the most secure TLS 1.3 protocol, ensuring this type of TLSv1 Alert downgrade protocol error never occurs.
2. Maintenance-Free Execution Environment:
   • Cloud sandboxes free developers from wrestling with complex local commands like brew upgrade openssl or reinstalling Python. All environmental dependencies and protocol negotiations are entirely managed and resolved by the cloud infrastructure.

6. Managed Sandbox Enterprise Setup & Billing Guide

In actual enterprise development or high-throughput Agent automated pipelines, rationally defining, configuring, and managing the cloud computing power and billing of Gemini Managed Agents is the core to reducing operational costs and ensuring compliance.

6.1 Detailed Explanation of Billing Models (How It's Billed)

The billing system for Gemini Managed Agents adopts a strict Pay-as-you-go and consumption-based billing model, primarily consisting of three parts:

1. Sandbox Compute Charges:
   • When the sandbox is in an Active state, billing is based on the consumed vCPU-hours and GiB Memory-hours.
   • Cold Start and Idle Optimization: Google Cloud provides the autoDestroyOnIdle mechanism. If the Agent task finishes and there is no new interaction within the specified time, the sandbox is instantaneously physically destroyed, halting the generation of compute charges.
2. Model Token Consumption:
   • The inference cost of the Agent's core brain is separated from the sandbox compute power, billed independently based on the number of Input Tokens and Output Tokens of the model (e.g., Gemini 3.5 Flash / Gemini 3.1 Pro).
3. Add-on Services:
   • Google Search Grounding: Each internet search is billed per 1,000 Queries.
   • Context Caching: Provides caching for ultra-long contexts or large codebases, billed per GiB-hour (effectively reducing Token costs for repeated inferences).

6.2 Cross-Region Creation and Data Residency (Region-based Allocation)

Considering Data Residency, Latency, and Service Availability, Google Cloud allows developers to specify concrete physical regions to provision cloud sandboxes:

• Data Compliance: Enterprise customers can mandate that sandboxes must run in europe-west1 (Belgium) or asia-northeast1 (Tokyo), ensuring sensitive code and interaction data never leave the specified jurisdiction.
• Physical Latency: Choosing a Region closest to your actual API request source (e.g., if developing locally in Hong Kong, selecting the asia-east1 Taiwan node) can minimize the sandbox's network cold-start time.

6.3 Detailed Dictionary of `settings.json` Parameters (Configuration Spec)

In the Antigravity client, all personalized configurations related to cloud sandboxes, billing, and regions are saved in the cloudSandbox block of ~/.gemini/antigravity-cli/settings.json.

Below is the complete parameter dictionary and their industrial-grade meanings:

{
  "enableTerminalSandbox": true, 
  "cloudSandbox": {
    "provider": "google-cloud",
    "model": "gemini-3.5-flash",
    "region": "us-central1",
    "ttlMinutes": 35,
    "autoDestroyOnIdle": true,
    "billingProjectId": "gcp-prod-billing-1029",
    "networkIsolation": "isolated-vpc",
    "enableInternetAccess": true
  }
}

🔑 Detailed Explanation of Core Parameters:

• provider (String): The physical provider of the sandbox. Optional values are "google-cloud" (Google managed cloud sandbox), "docker" (local physical machine container), or "local" (local system-level isolation).
• model (String): The LLM version driving the Managed Agent. The highly cost-effective "gemini-3.5-flash" is recommended; complex architectural tasks can be upgraded to "gemini-3.1-pro".
• region (String): Specifies the region where the cloud sandbox physical container is created. For example: "us-central1" (US Central), "europe-west3" (Frankfurt), "asia-east1" (Taiwan).
• ttlMinutes (Integer): Forced maximum Time-To-Live (lifecycle upper limit). In minutes. Exceeding this time, regardless of whether the task has finished, the cloud will automatically force physical reclamation to prevent processes from falling into infinite loops and generating astronomical bills.
• autoDestroyOnIdle (Boolean): Idle auto-destroy switch. When set to true, if the Agent has no new interactions within 5 minutes after completing the current task, the cloud sandbox automatically shuts down.
• billingProjectId (String): The bound Google Cloud Project ID. All compute charges, Token fees, and network traffic fees generated in the cloud sandbox are directly deducted from this project's GCP billing.
• networkIsolation (String): Network isolation mode. "isolated-vpc" means the sandbox is encapsulated within an enterprise-exclusive secure VPC, enabling secure access to enterprise intranet databases; "public-egress" means routing directly through a public egress.
• enableInternetAccess (Boolean): Whether to allow programs inside the sandbox to access the external internet. If handling highly confidential projects, this can be set to false. In this case, Python scripts within the sandbox will be unable to call external APIs like Telegram, entering a state of complete "standalone physical isolation."

🔗 7. Official Authoritative Resources and Links (Official References)

For in-depth learning and production deployment, please refer to Google's official authoritative documentation and real-time billing calculators:

• 🌐 Google AI Studio Developer Platform: https://aistudio.google.com/ (Obtain and manage your API Keys and account quotas)
• 🌐 Google Gemini API Official Development Documentation: https://ai.google.dev/gemini-api/docs (Standard guidelines for Managed Agents and interactive APIs)
• 🌐 Google Cloud Vertex AI Official Pricing Details Page: https://cloud.google.com/vertex-ai/pricing (The most real-time billing standards for vCPU, memory, and LLM Tokens)
• 🌐 Google Antigravity Official Portal: https://antigravity.google (View system instructions regarding the client, CLI tool agy, and the latest Agent architectures)

8. Conclusion

1. Unsandboxed Mode is suitable for quickly running highly trusted lightweight tools, but it hands over all the keys to the system to the AI;
2. Local Sandbox Mode is a highly cost-effective local security lock, achieving free resource usage and real-time feedback without exposing core local privacy data to the AI;
3. Cloud Sandbox Mode is the ultimate cloud-native production environment. It provides physical-level network and system isolation, automatically destroying itself after completing development and scheduled daemon tasks, representing the secure future of AI collaborative development.