> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gentility.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Read File from VM

> Reads files from VM instances and returns content as JSON.

Reads files from VM instances and returns their content as JSON. This endpoint supports reading any file within the VM filesystem that the user has access to.

## Path Parameter

The `{path}` parameter is a wildcard that captures the full file path within the VM. For example:

* `/home/user/script.py`
* `/tmp/output.json`
* `/workspace/data/results.csv`
* `/etc/hosts` (if readable)

## Use Cases

* **Result Retrieval**: Read output files generated by executed commands
* **Configuration Access**: Read configuration files and settings
* **Data Export**: Access data files, logs, and generated reports
* **AI Agent File Access**: Allow AI agents to read files they've created or need to analyze

## Response Examples

### Text File Content

```json theme={null}
{
  "file_path": "/home/user/script.py",
  "content": "#!/usr/bin/env python3\n\nprint('Hello, Gentility!')\n\n# This is a sample Python script\nfor i in range(5):\n    print(f'Count: {i}')",
  "instance_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

### JSON File Content

```json theme={null}
{
  "file_path": "/tmp/analysis_results.json",
  "content": "{\n  \"summary\": \"Data analysis complete\",\n  \"total_records\": 1500,\n  \"insights\": [\n    \"Peak usage occurs at 3 PM\",\n    \"Weekend traffic is 40% lower\"\n  ]\n}",
  "instance_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

### Binary File Handling

For binary files, the content will be base64 encoded:

```json theme={null}
{
  "file_path": "/home/user/chart.png", 
  "content": "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAABH...",
  "instance_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

### File Not Found

```json theme={null}
{
  "error": "file_not_found",
  "message": "File '/nonexistent/path.txt' not found in instance"
}
```

### Instance Not Found

```json theme={null}
{
  "error": "instance_not_found", 
  "message": "No instance found for profile 6ba7b810-9dad-11d1-80b4-00c04fd430c8 and room ai-session-123"
}
```

## Alternative: Direct File Access

For unauthenticated access (useful for AI agents), you can also use the direct file access endpoint:

```
GET /vm/{instance_id}/file/{path}
```

This endpoint:

* Requires no authentication
* Serves files with appropriate MIME types
* Returns raw file content (not JSON wrapped)
* Suitable for images, PDFs, and other binary files

## Best Practices

* **File Paths**: Use absolute paths starting from `/` or relative paths from the VM's home directory
* **Large Files**: Be mindful that very large files will be returned as base64 encoded strings
* **Security**: Only files accessible to the VM user can be read
* **Caching**: File content is read fresh on each request - no caching is performed
* **Error Handling**: Always check for 404 errors when files might not exist


## OpenAPI

````yaml GET /api/profile/{profile_id}/room/{room_id}/file/{path}
openapi: 3.1.0
info:
  title: Gentility AI API
  description: >-
    API for instant development environments and AI agent tools. Spin up
    isolated virtual machines, execute commands, access files, and more.
  license:
    name: Proprietary
  version: 1.0.0
  contact:
    name: Gentility AI Support
    url: https://gentility.ai
    email: support@gentility.ai
servers:
  - url: https://api.gentility.ai
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: VM Management
    description: Operations for creating and managing VM instances
  - name: Command Execution
    description: Execute shell commands within VM instances
  - name: File Operations
    description: Read and access files within VM instances
  - name: AI Tools
    description: Tool schemas and capabilities for AI agents
  - name: Profile Management
    description: VM configuration templates and settings
paths:
  /api/profile/{profile_id}/room/{room_id}/file/{path}:
    get:
      tags:
        - File Operations
      summary: Read file from VM instance
      description: Reads files from VM instances and returns content as JSON.
      parameters:
        - name: profile_id
          in: path
          required: true
          description: UUID of the profile
          schema:
            type: string
            format: uuid
        - name: room_id
          in: path
          required: true
          description: Room identifier
          schema:
            type: string
        - name: path
          in: path
          required: true
          description: File path within the VM (wildcard path parameter)
          schema:
            type: string
      responses:
        '200':
          description: File content retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileContent'
        '404':
          description: File or instance not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    FileContent:
      type: object
      required:
        - file_path
        - content
        - instance_id
      properties:
        file_path:
          type: string
          description: Path to the file within the VM
        content:
          type: string
          description: File content as string
        instance_id:
          type: string
          format: uuid
          description: Instance containing the file
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Error code or type
        message:
          type: string
          description: Human-readable error message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key authentication using Bearer token format: ''Bearer rk_live_<key>'''

````