Meta Agent Tools
PT

Back to the catalog

gas-fakes-ext

Gemini CLI Extension for Sandboxed Google Apps Script - This Gemini CLI extension provides a secure, sandboxed environment for developing an

Open source Open in the app JSON README (API)

About

Gemini CLI Extension for Sandboxed Google Apps Script - This Gemini CLI extension provides a secure, sandboxed environment for developing and testing Google Apps Script (GAS) projects locally.

Details

Kind
Plugins
Topic
Developer tools
Publisher
mhawksey
Origin
gemini
Category
ferramentas
Version
0.3.6
Stars
8
Forks
1
Last push
2025-10-21T22:40:18Z
Repository state
ativo
Language
JavaScript
License
Apache-2.0
Added
2026-08-30 14:13:39
Updated
2026-08-30 14:13:39
Origin id
mhawksey/gas-fakes-ext

README

# Gemini CLI Extension for Sandboxed Google Apps Script

This Gemini CLI extension provides a secure, sandboxed environment for developing and testing Google Apps Script (GAS) projects locally. It leverages Bruce Mcpherson's [`gas-fakes`](https://github.com/brucemcpherson/gas-fakes) library to create a safe sandbox for executing GAS, which is particularly useful when working with AI-generated code.

## The Problem: The Security Risk of AI-Generated Apps Script

Google Apps Script is a powerful platform for automating Google Workspace, but its permission model can be dangerously broad. When you run a script, it often requires extensive, irrevocable access to your Google account and data. This presents a significant security concern, especially when using code generated by AI or from untrusted sources. You are essentially giving a black box full access to your digital life.

This extension is designed to solve this problem by providing a local development environment where you can safely execute and test Google Apps Script code without granting it any permissions to your Google account.

## Features

*   **Secure Sandbox:**  Uses `gas-fakes` to create a sandboxed environment, preventing scripts from accessing your Google account or any sensitive data.
*   **Local Development:**  Develop and test your Google Apps Script projects on your local machine.
*   **Easy Project Setup:**  Quickly initialize a new Google Apps Script project with the necessary configuration for local development.
*   **AI-Friendly:**  Ideal for experimenting with AI-generated Google Apps Script code without security risks.
*   **Conversational Automation:**  Integrates with the Model Context Protocol (MCP) to allow for conversational automation of Google Workspace tasks.

## Getting Started

To learn more about managing Gemini CLI Extensions, including installation, uninstallation, and updates, please see the [official documentation](https://google-gemini.github.io/gemini-cli/docs/extensions/).

### Prerequisites

*   [Google Gemini CLI](https://google-gemini.github.io/gemini-cli/docs/getting-started.html)

### Installation

1.  Install the extension:

    ```bash
    gemini extensions install https://github.com/mhawksey/gas-fakes-ext
    ```

2.  Navigate to your working directory and start Gemini:

    ```bash
    gemini
    ```

## Commands

This extension provides the following commands under the `gas` namespace. These can be run directly within the Gemini prompt using `/gas:<command>`.

### `/gas:init`

Initializes a new Google Apps Script project in the current directory. It creates the following files and directories:

```
.
├── .clasp.json
├── .claspignore
├── node_modules/
├── package.json
├── run.js
└── src/
    └── Code.js
```

After running `/gas:init`, you can ask Gemini to install the dependencies and test your script.

### `/gas:new "<your prompt>"`

Generates a Google Apps Script file (`src/Code.js`) and a corresponding runner script (`run.js`) based on your prompt. This is useful for quickly scaffolding a script from a natural language description.

**Example:**

```
/gas:new "create a new Google Doc and write 'Hello, World!' to it"
```

## GEMINI.md and System Instructions

This extension includes a `GEMINI.md` file, which provides system instructions to the Gemini model. This file contains information about how to use the `gas-fakes` library, ensuring that the model can generate code that is compatible with the sandboxed environment.

When you use the `/gas:new` command, the contents of `GEMINI.md` are automatically included in the prompt, providing the model with the necessary context to generate safe and effective Google Apps Script code.

## Conversational Automation with MCP

This extension also includes tools for integrating with Model Context Protocol (MCP) servers. MCP allows Gemini to discover and interact with external tools and services, enabling powerful conversational automation workflows.

### Local `gas-fakes` MCP Server

This project includes a script to run the `gas-fakes` library as a local MCP server. This allows Gemini to interact with the sandboxed Google Apps Script environment, discover its capabilities, and execute scripts within it. The packaged MCP server now exposes advanced sandbox controls, allowing for fine-grained control over the execution environment.

For more information on this approach, see this article: [Secure and Conversational Google Workspace Automation: Integrating Gemini CLI with a gas-fakes MCP Server](https://tanaikech.github.io/2025/09/30/secure-and-conversational-google-workspace-automation-integrating-gemini-cli-with-a-gas-fakes-mcp-server/)

### Google Workspace MCP

For more direct interaction with Google Workspace APIs, you can use the official Google Workspace MCP. This tool allows you to interact with Google Workspace services directly from the Gemini CLI.

For more information, see the official documentation: [Use Large Language Models (LLMs) to develop on Google Workspace](https://developers.google.com/workspace/guides/build-with-llms#mcp)

## How it Works: The `gas-fakes` Sandbox

This extension uses Bruce Mcpherson's `gas-fakes` library, which emulates the Google Apps Script environment locally. The `run.js` script sets up a secure sandbox using Node.js's `vm` module and executes your GAS code within that sandbox. This prevents the script from accessing any external resources or APIs, ensuring a safe execution environment.

The sandbox can be configured to have granular control over which files a script can access, providing a safe way to test scripts that interact with your Google Drive files.

## Advanced Sandbox Configuration

The packaged MCP server exposes a number of advanced controls that allow you to fine-tune the sandbox environment. These controls can be passed as parameters to the `run-gas-fakes-test` tool.

*   **`strictSandbox` (boolean):** When `true` (and `sandboxMode` is active), attempts to access non-whitelisted, non-session files will throw an error. If `false`, access is allowed.
*   **`cleanup` (boolean):** If `true`, `ScriptApp.__behavior.trash()` moves all session-created files to Google Drive trash. Set to `false` to leave artifacts for inspection.
*   **`whitelistItems` (array of objects):** Use this to access existing files on Google Drive. Provide an array of objects, where each object has a file ID and optional read/write/trash permissions.
    ```javascript
    [
      { id: "FILE_ID_1", write: true },
      { id: "FILE_ID_2", read: true, trash: false },
    ]
    ```
*   **`serviceControls` (object):** Per-service settings that override global settings. The key is the service name (e.g., `'DriveApp'`).
    ```javascript
    {
      "DriveApp": { "enabled": false },
      "SpreadsheetApp": { "sandboxMode": false },
    }
    ```
*   **`methodWhitelist` (object):** An object where the key is the service name and the value is an array of permitted method names.
    ```javascript
    {
      "DriveApp": ["getFiles", "createFile"],
    }
    ```

## Acknowledgement

This extension builds upon the work of [Bruce Mcpherson](https://github.com/brucemcpherson) and his [`gas-fakes`](https://github.com/brucemcpherson/gas-fakes) library. The concept of a secure sandbox for AI-generated Apps Script is further explained in this [article by Bruce Mcpherson](https://pulse.appsscript.info/p/2025/09/a-secure-sandbox-for-ai-generated-apps-script-how-to-experiment-with-confidence/). This Gemini CLI Extension would also not have been possible without the contributions of [Kanshi Tanaike](https://github.com/tanaikech), whose work on the `gas-fakes` sandbox and MCP server has been instrumental in the development of this extension.

More