Virtual File System
RTC Agent builds a complete virtual file system in the browser. AI operates on files using tools like ls, read, write, grep, and find, just like working with a local terminal — but all data always stays within the user’s browser.
Why a File System
Section titled “Why a File System”💡 Core Insight: LLMs are already very good at operating file systems. Instead of making the AI learn custom APIs, give it a file system — it can immediately
ls,read,grep, andwrite.
Directory Structure
Section titled “Directory Structure”| Directory | Purpose | Content Source |
|---|---|---|
/functions/ | Function documentation | Auto-generated after the host app registers Functions |
/scenarios/ | Scenario documentation | Markdown workflows provided by the business side |
/scripts/ | Executable scripts | Saved by AI via the script tool |
/AGENT.md | System entry point | Auto-generated template describing directory structure and tools |
File Operations
Section titled “File Operations”The virtual file system provides 6 operations covering all file interactions the AI needs:
| Operation | Function | Key Parameters |
|---|---|---|
ls | List directory contents | path (default /) |
read | Read file contents | path (required), offset / limit (pagination) |
write | Create or write to file | path, content (required), mode (overwrite / append) |
find | Search by file name | pattern (glob), path |
grep | Search by file content | pattern (regex), path, caseSensitive |
remove | Delete file | path |
⚠️
removeis an internal API of the virtual file system and is not currently exposed to AI as an RTC tool. AI cannot directly delete files.
Paginated Reading
Section titled “Paginated Reading”Large files support paginated reading to avoid loading too much content at once:
Path Specifications
Section titled “Path Specifications”| Rule | Description |
|---|---|
| Root directory | / |
| Separator | / (forward slash) |
| Auto-conversion | All paths are automatically converted to absolute paths |
| Path traversal | .. is rejected directly, without parsing |
| Directories | Logical concept, not stored separately, derived from path prefixes |
File Type Inference
Section titled “File Type Inference”File types are automatically inferred from the path prefix, no explicit specification needed:
Storage Mechanism
Section titled “Storage Mechanism”| Feature | Description |
|---|---|
| Storage Engine | IndexedDB (wrapped by Dexie.js) |
| Primary Key | File path |
| Large Files | Stored and retrieved as whole, supports paginated reading |
| Read Behavior | Each read queries the latest data directly, no cache layer |
| Capacity | Subject to browser IndexedDB quota (typically hundreds of MB) |
Initialization
Section titled “Initialization”At system startup, /AGENT.md is automatically checked. If it doesn’t exist, a template file is auto-generated to describe the directory structure and available tools to the AI — ensuring the AI knows “what’s in the file system” as soon as it comes online.
Security Constraints
Section titled “Security Constraints”| Constraint | Description |
|---|---|
| 🔒 Path traversal protection | .. is rejected directly |
| 🔐 Permission control | Determined by work mode |
| 💾 Capacity limits | Subject to browser IndexedDB quota |
| 🚫 No cross-origin access | File system is fully isolated within the browser sandbox |
Next Steps
Section titled “Next Steps”- Remote Tool Calling — Learn how AI calls these file operations
- Script Engine — Learn how scripts in the
/scripts/directory are executed - Skill System — Learn how functions in the
/functions/directory are registered