File System Access Control and Security

Relevant source files

• Google/Antigravity/Fast Prompt.txt

Purpose and Scope

This document details the file system access control and security model implemented in Google Antigravity's Fast Prompt system. It covers workspace-based access restrictions, the special .gemini system directory, absolute path requirements, and security enforcement mechanisms that prevent unauthorized file operations.

For information about Antigravity's overall architecture and identity, see System Architecture and Identity. For details on Knowledge Items storage which utilizes the .gemini directory, see Knowledge Items (KI) Architecture.

---

Workspace Access Control Model

Antigravity implements a strict workspace-based security model where file operations are restricted to explicitly authorized directories. Access is controlled through a workspace URI to CorpusName mapping system that defines permissible file system boundaries.

Workspace Definition and Mapping

Each active workspace is defined by two components:

• URI: The absolute file system path (Windows-style or POSIX-style)
• CorpusName: A normalized identifier for the workspace (typically POSIX-style)

The mapping between URIs and CorpusNames is provided in the <user_information> section at session initialization:

The user has 1 active workspaces, each defined by a URI and a CorpusName.
Multiple URIs potentially map to the same CorpusName.
The mapping is shown as follows in the format [URI] -> [CorpusName]:
c:\Users\Lucas\OneDrive\Escritorio\antigravity -> c:/Users/Lucas/OneDrive/Escritorio/antigravity

This mapping defines the security boundary for all file system operations. Note that multiple URIs can map to the same CorpusName, allowing for flexible workspace configurations while maintaining consistent security enforcement.

Sources: Google/Antigravity/Fast Prompt.txt9-10

Access Control Rules

The system enforces the following strict rules defined in the <user_information> section:

Rule	Description	Enforcement Level	Source Line
Workspace Restriction	"You are not allowed to access files not in active workspaces"	Mandatory	Line 12
Read/Write Scope	"You may only read/write to the files in the workspaces listed above"	Mandatory	Line 12
.gemini Special Access	Access to C:\Users\Lucas\.gemini "but ONLY for for usage specified in your system instructions"	Restricted	Line 12
Code Placement	"Avoid writing project code files to tmp, in the .gemini dir, or directly to the Desktop and similar folders unless explicitly asked"	Recommended	Line 13
Multi-Workspace Support	"The user has 1 active workspaces, each defined by a URI and a CorpusName"	Supported	Line 9
Path Normalization	"Multiple URIs potentially map to the same CorpusName"	Automatic	Line 9

These rules are enforced across all file system tools including view_file, write_to_file, replace_file_content, multi_replace_file_content, list_dir, find_by_name, codebase_search, and grep_search.

Sources: Google/Antigravity/Fast Prompt.txt9-14

Workspace Access Control Architecture

This diagram shows how the <user_information> section defines security boundaries and how file system tools enforce them:

Sources: Google/Antigravity/Fast Prompt.txt7-609

---

The .gemini Directory - Special System Access

Purpose and Scope

The .gemini directory located at C:\Users\Lucas\.gemini represents a special security boundary. Unlike user workspaces, this directory is reserved exclusively for system-level operations and cannot be used for storing user project code.

Directory Structure

The .gemini directory contains system-managed data organized by workspace CorpusName:

C:\Users\Lucas\.gemini\
└── antigravity\                                  # CorpusName-based directory
    ├── knowledge\                                # Knowledge Items storage
    │   ├── [KI-ID]\                             # Individual KI directory
    │   │   ├── metadata.json                    # KI summary, timestamps, references
    │   │   └── artifacts\                       # Related files and documentation
    │   │       ├── architecture_overview.md
    │   │       ├── implementation_patterns.md
    │   │       └── ...
    │   └── ...
    └── brain\                                    # Conversation persistence
        └── [conversation-id]\                    # Individual conversation
            └── .system_generated\
                └── logs\                         # Conversation logs
                    ├── overview.txt
                    └── task_*.txt

The path C:\Users\Lucas\.gemini\antigravity\knowledge is referenced in the system instructions for Knowledge Items discovery.

Sources: Google/Antigravity/Fast Prompt.txt204-279

Access Restrictions

Operation Type	Allowed	Restrictions
Read KI metadata	✓	For knowledge discovery only
Read KI artifacts	✓	Referenced by metadata paths
Read conversation logs	✓	For context retrieval
Write project code	✗	Explicitly forbidden
Write user files	✗	System usage only

The system explicitly warns against writing project code to .gemini:

"Avoid writing project code files to tmp, in the .gemini dir, or directly to the Desktop and similar folders unless explicitly asked."

Sources: Google/Antigravity/Fast Prompt.txt12-204

.gemini Directory Security Model

This diagram shows how tools interact with the .gemini system directory and the validation rules from lines 12-13:

Sources: Google/Antigravity/Fast Prompt.txt12-609

---

Absolute Path Requirements

Mandatory Path Format

All file operations in Antigravity must use absolute paths. Relative paths are not supported and will result in errors.

Tool Calling Guidance:

"When using tools that accept file path arguments, ALWAYS use the absolute file path."

Sources: Google/Antigravity/Fast Prompt.txt17

Affected Tools and Parameters

The absolute path requirement defined in the <tool_calling> section (line 17) applies to all file system tools. Each tool defines specific path parameters with type signatures from the namespace functions block:

Tool Function	Path Parameter	Type	Line Reference	Additional Security Parameters
view_file	AbsolutePath	string	572-581	StartLine?: number, EndLine?: number
view_file_outline	AbsolutePath	string	583-591	ItemOffset?: number
search_in_file	AbsolutePath	string	534-542	Query: string
view_code_item	File	string	552-559	NodePaths: string[]
write_to_file	TargetFile	string	593-609	Overwrite: boolean, EmptyFile: boolean
replace_file_content	TargetFile	string	462-488	AllowMultiple: boolean, TargetLintErrorIds?: string[]
multi_replace_file_content	TargetFile	string	438-460	ReplacementChunks: any[], TargetLintErrorIds?: string[]
list_dir	DirectoryPath	string	412-418	None
find_by_name	SearchDirectory	string	360-380	Pattern: string, MaxDepth?: number
codebase_search	TargetDirectories	string[]	338-346	Query: string
grep_search	SearchPath	string	394-410	Query: string, IsRegex?: boolean

All tools also include waitForPreviousTools?: boolean for execution sequencing control.

Tool Path Requirements Diagram

Sources: Google/Antigravity/Fast Prompt.txt15-609

Rationale

Absolute path requirements serve multiple security purposes:

1. Unambiguous Access Control: Eliminates ambiguity in workspace boundary checking
2. Prevents Path Traversal: Blocks relative path attacks (e.g., ../../etc/passwd)
3. Explicit Authorization: Forces explicit declaration of target locations
4. Audit Trail: Creates clear records of exact file system locations accessed

Sources: Google/Antigravity/Fast Prompt.txt17

---

File Writing Restrictions and Code Placement

Prohibited Write Locations

Beyond workspace restrictions, Antigravity enforces additional rules about where project code may be written:

Location	Status	Rationale
Active Workspaces	✓ Allowed	Primary code storage
/tmp or temp directories	✗ Forbidden	Ephemeral, may be cleared
.gemini directory	✗ Forbidden	Reserved for system use
Desktop	✗ Forbidden	User UI space, not project root
Similar user folders	✗ Forbidden	Downloads, Documents, etc.

Exception: These locations may be used only if the user explicitly requests it.

Sources: Google/Antigravity/Fast Prompt.txt13

Code Placement Decision Tree

Sources: Google/Antigravity/Fast Prompt.txt12-13

File Writing Tools Security Parameters

The file writing tools include multiple security-relevant parameters. These type definitions from namespace functions show the security controls:

write_to_file Type Definition (Lines 593-609)

replace_file_content Type Definition (Lines 462-488)

multi_replace_file_content Type Definition (Lines 438-460)

Security Features Summary

Parameter	Security Function	Tool(s)	Behavior
TargetFile	Absolute path enforcement	All write tools	Must be absolute (line 17); validated against workspace boundaries (line 12)
Overwrite	Accidental overwrite prevention	write_to_file	Must explicitly set to true to overwrite existing files
EmptyFile	Empty file creation safety	write_to_file	When true, creates empty file without content
AllowMultiple	Multi-occurrence control	replace_file_content	Controls whether to replace multiple occurrences
TargetLintErrorIds	Lint integration	replace_file_content, multi_replace_file_content	Links edits to specific lint errors
Complexity	Review importance	All write tools	1-10 rating signals need for user review
waitForPreviousTools	Sequencing control	All tools	Controls parallel vs sequential execution for safety

Sources: Google/Antigravity/Fast Prompt.txt17-609

---

Security Boundaries and Enforcement

Multi-Layer Security Model

Antigravity implements defense in depth through multiple security layers:

Sources: Google/Antigravity/Fast Prompt.txt9-18

Security Guarantees

The multi-layer model provides these guarantees:

1. No Unauthorized Access: Files outside workspaces and .gemini cannot be accessed
2. Clear Intent: Write operations to restricted areas require explicit user consent
3. Path Safety: Relative paths cannot be used to bypass workspace boundaries
4. Separation of Concerns: System data (.gemini) isolated from user code
5. Explicit Overwrite: File overwrites require explicit flag setting

Sources: Google/Antigravity/Fast Prompt.txt12-17

---

Tool-Level Security Implementation

File System Tool Categories

Different tool categories enforce different aspects of the security model:

Tool Category	Security Focus	Key Tools
Reading Tools	Workspace boundary validation	view_file, view_file_outline, search_in_file
Writing Tools	Overwrite protection, location validation	write_to_file, replace_file_content, multi_replace_file_content
Directory Tools	Traversal boundaries	list_dir, find_by_name
Search Tools	Scope limitation	codebase_search, grep_search

Sources: Google/Antigravity/Fast Prompt.txt320-611

Tool Parameter Security Features

Each tool implements specific security parameters that enforce access control:

Sources: Google/Antigravity/Fast Prompt.txt338-609

Workspace Matching Algorithm

The system uses the following logic to validate file access:

1. Extract Absolute Path: Get the target path from tool parameters
2. Normalize Path: Convert to canonical form (forward slashes, resolve symlinks)
3. Check Active Workspaces: Match against all URI → CorpusName mappings
4. Check Special Directories: If path starts with .gemini, validate system usage
5. Evaluate Intent: For writes, check if target is appropriate for operation type
6. Execute or Deny: Proceed with operation or return authorization error

Sources: Google/Antigravity/Fast Prompt.txt9-17

---

Related Security Considerations

Integration with Other Systems

The file system access control integrates with other Antigravity security features:

• Knowledge Items: Use .gemini directory with read-only access for agents (Knowledge Items (KI) Architecture)
• Conversation Logs: Stored in .gemini/antigravity/brain with read-only access (Conversation Logs and Persistent Context)
• Workflow Execution: Workflows in .agent/workflows follow workspace restrictions (Workflow System and Turbo Annotations)

Command Execution Security

The run_command tool (lines 490-502) enforces working directory constraints consistent with file operation security:

The system prompt specifies the execution environment on line 490:

"PROPOSE a command to run on behalf of the user. Operating System: windows. Shell: powershell."

Command Execution Security Validation Flow

Command Execution Security Constraints

Parameter	Security Function	Validation	Line Reference
Cwd	Working directory restriction	Must be within active workspace URI from line 10	Lines 12, 494
SafeToAutoRun	User approval bypass control	Only true for safe commands (reads, standard dev tools)	Line 496
WaitMsBeforeAsync	Background process control	Controls when command is backgrounded	Line 498
CommandLine	Command string	Executed in powershell on Windows	Lines 490, 492

The Cwd parameter is validated against workspace boundaries (line 12) before command execution, ensuring that commands execute within authorized directories only. Additionally, the command must not be run from within C:\Users\Lucas\.gemini if it's writing project code (line 13).

Related Command Management Tools

Tool	Purpose	Line Reference
command_status(CommandId, WaitDurationSeconds, OutputCharacterCount?)	Check status of background command	Lines 348-358
send_command_input(CommandId, Input?, Terminate?)	Interact with running command or terminate it	Lines 514-524
read_terminal(Name, ProcessID)	Read full terminal content	Lines 504-512

Sources: Google/Antigravity/Fast Prompt.txt12-524

---

Summary

Antigravity's file system access control implements a comprehensive security model based on:

1. Workspace-based authorization with explicit URI to CorpusName mappings
2. Special system directory (.gemini) with restricted usage
3. Absolute path requirements for all file operations
4. Smart write restrictions preventing code placement in inappropriate locations
5. Multi-layer validation enforcing security at multiple points
6. Tool-level safeguards including overwrite protection and path validation

This architecture ensures that file operations remain within authorized boundaries while maintaining flexibility for legitimate system operations like knowledge retrieval and context management.

Sources: Google/Antigravity/Fast Prompt.txt7-611