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

# Read File from Sandbox

> Read file contents from the sandbox as text using the HopX VM Agent API. Learn how to use GET /files/read endpoint to retrieve file contents, handle text and binary files, manage encoding, and process file data. Includes request examples and response formats.

Read file contents from the sandbox. Only allowed paths like `/workspace` and `/tmp` can be read.

## Endpoint

```
GET /files/read
```

## Request

### Headers

```
Authorization: Bearer YOUR_JWT_TOKEN
```

### Query Parameters

| Parameter | Type   | Required | Description                             |
| --------- | ------ | -------- | --------------------------------------- |
| `path`    | string | Yes      | File path (e.g., `/workspace/data.txt`) |

### Example Request

```bash theme={null}
curl "https://sandbox_abc123xyz.hopx.dev/files/read?path=/workspace/data.txt" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

## Response

### Success (200 OK)

```json theme={null}
{
  "content": "Hello World\nLine 2\nLine 3\n",
  "path": "/workspace/data.txt",
  "size": 30
}
```

### Response Fields

| Field     | Type    | Description           |
| --------- | ------- | --------------------- |
| `content` | string  | File contents as text |
| `path`    | string  | File path             |
| `size`    | integer | File size in bytes    |

## Status Codes

| Code | Description                                    |
| ---- | ---------------------------------------------- |
| 200  | Success                                        |
| 401  | Unauthorized                                   |
| 403  | Path not allowed (outside allowed directories) |
| 404  | File not found                                 |

## Errors

### File Not Found (404)

```json theme={null}
{
  "error": "File not found: /workspace/nonexistent.txt",
  "code": "FILE_NOT_FOUND"
}
```

**Cause:** The file doesn't exist.

**Fix:** Verify the file path and ensure the file exists.

### Path Not Allowed (403)

```json theme={null}
{
  "error": "Path not allowed: /etc/passwd",
  "code": "FORBIDDEN"
}
```

**Cause:** The path is outside allowed directories.

**Fix:** Only read files from `/workspace`, `/tmp`, or other explicitly allowed paths.

## Allowed Paths

You can read files from:

* `/workspace/*` - Main working directory
* `/tmp/*` - Temporary files
* Other paths may be allowed depending on sandbox configuration

## Use Cases

### Read Configuration File

```bash theme={null}
curl "https://sandbox_abc123xyz.hopx.dev/files/read?path=/workspace/config.json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" | jq '.content | fromjson'
```

### Read Log File

```bash theme={null}
curl "https://sandbox_abc123xyz.hopx.dev/files/read?path=/workspace/app.log" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" | jq -r '.content'
```

### Read CSV Data

```bash theme={null}
curl "https://sandbox_abc123xyz.hopx.dev/files/read?path=/workspace/data.csv" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" | jq -r '.content' | head -10
```

### Check File Size

```bash theme={null}
curl "https://sandbox_abc123xyz.hopx.dev/files/read?path=/workspace/large_file.txt" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" | jq '.size'
```

### Read and Process

```python theme={null}
import requests
import json

url = "https://sandbox_abc123xyz.hopx.dev/files/read"
headers = {"Authorization": "Bearer YOUR_JWT_TOKEN"}
params = {"path": "/workspace/results.json"}

response = requests.get(url, headers=headers, params=params)
data = response.json()

# Parse JSON content
file_content = json.loads(data["content"])
print(f"Read {data['size']} bytes from {data['path']}")
print(f"Data: {file_content}")
```

## Related

* **SDK**: [sandbox.files.read()](/sdk/python/files#read) - Python SDK method
* [CLI File Operations](/cli/commands/files) - File operations from CLI

## Next Steps

* **[Write File](/api/vm-agent/write-file)** - Write file contents
* **[List Files](/api/vm-agent/list-files)** - List directory contents
* **[File Exists](/api/vm-agent/file-exists)** - Check if file exists